Filters API Reference

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

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

Operator	Description	Example
“ (empty)	Equal	`{"operator": "", "value": [100]}`
`iexact`	Case insensitive equal	`{"operator": "iexact", "value": ["test"]}`
`lt`	Less than	`{"operator": "lt", "value": [100]}`
`lte`	Less than or equal	`{"operator": "lte", "value": [100]}`
`gt`	Greater than	`{"operator": "gt", "value": [100]}`
`gte`	Greater than or equal	`{"operator": "gte", "value": [100]}`
`contains`	Contains substring	`{"operator": "contains", "value": ["keyword"]}`
`icontains`	Case insensitive contains	`{"operator": "icontains", "value": ["keyword"]}`
`startswith`	Starts with	`{"operator": "startswith", "value": ["prefix"]}`
`endswith`	Ends with	`{"operator": "endswith", "value": ["suffix"]}`
`in`	In list (array or text)	`{"operator": "in", "value": ["val1", "val2"]}`
`isnull`	Is null	`{"operator": "isnull", "value": [true]}`
`not`	Not 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:

Parameter	Type	Default	Description
`start_time`	ISO 8601 datetime	1 hour ago	Start of time range
`end_time`	ISO 8601 datetime	Current time	End of time range
`page`	integer	1	Page number
`page_size`	integer	50	Results per page (max 1000)
`sort_by`	string	`-timestamp`	Field to sort by (prefix `-` for descending)
`environment`	string	All	Filter 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"]
>       }
>     }
>   }'