Reference

Filters API Reference

This document describes the filtering system used across Respan endpoints (spans, traces, threads, etc.).

Filter Structure

Filters are passed in the request body as a JSON object:

1{
2  "filters": {
3    "field_name": {
4      "operator": "gt",
5      "value": [100]
6    }
7  }
8}

Filter Operators

OperatorDescriptionExample
“ (empty)Equal{"operator": "", "value": [100]}
iexactCase insensitive equal{"operator": "iexact", "value": ["test"]}
ltLess than{"operator": "lt", "value": [100]}
lteLess than or equal{"operator": "lte", "value": [100]}
gtGreater than{"operator": "gt", "value": [100]}
gteGreater than or equal{"operator": "gte", "value": [100]}
containsContains substring{"operator": "contains", "value": ["keyword"]}
icontainsCase insensitive contains{"operator": "icontains", "value": ["keyword"]}
startswithStarts with{"operator": "startswith", "value": ["prefix"]}
endswithEnds with{"operator": "endswith", "value": ["suffix"]}
inIn list (array or text){"operator": "in", "value": ["val1", "val2"]}
isnullIs null{"operator": "isnull", "value": [true]}
notNot equal{"operator": "not", "value": [100]}

Filter Examples

Numeric Filters

Filter by cost greater than $0.01:

1{
2  "filters": {
3    "cost": {
4      "operator": "gt",
5      "value": [0.01]
6    }
7  }
8}

Filter by token count range:

1{
2  "filters": {
3    "total_tokens": {
4      "operator": "gte",
5      "value": [100]
6    }
7  }
8}

String Filters

Filter by customer identifier:

1{
2  "filters": {
3    "customer_identifier": {
4      "operator": "",
5      "value": ["user@example.com"]
6    }
7  }
8}

Filter by workflow name (prefix):

1{
2  "filters": {
3    "workflow_name": {
4      "operator": "startswith",
5      "value": ["chat_"]
6    }
7  }
8}

Multiple Filters

Combine multiple conditions:

1{
2  "filters": {
3    "cost": {
4      "operator": "gte",
5      "value": [0.01]
6    },
7    "environment": {
8      "operator": "",
9      "value": ["production"]
10    },
11    "error_count": {
12      "operator": "",
13      "value": [0]
14    }
15  }
16}

Metadata Filters

To filter custom properties in metadata, prefix the field with metadata__:

1{
2  "filters": {
3    "metadata__user_id": {
4      "operator": "",
5      "value": ["user123"]
6    }
7  }
8}

Query Parameters

Most endpoints also support these query parameters:

ParameterTypeDefaultDescription
start_timeISO 8601 datetime1 hour agoStart of time range
end_timeISO 8601 datetimeCurrent timeEnd of time range
pageinteger1Page number
page_sizeinteger50Results per page (max 1000)
sort_bystring-timestampField to sort by (prefix - for descending)
environmentstringAllFilter by environment

Complete Example

$curl -X POST "https://api.respan.ai/api/traces/list/?start_time=2024-01-15T00:00:00Z&end_time=2024-01-15T23:59:59Z&page_size=20" \
>  -H "Authorization: Bearer <your-api-key>" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "filters": {
>      "total_cost": {
>        "operator": "gte",
>        "value": [0.01]
>      },
>      "environment": {
>        "operator": "",
>        "value": ["production"]
>      }
>    }
>  }'