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:

{
  "filters": {
    "field_name": {
      "operator": "gt",
      "value": [100]
    }
  }
}

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:

{
  "filters": {
    "cost": {
      "operator": "gt",
      "value": [0.01]
    }
  }
}

Filter by token count range:

{
  "filters": {
    "total_tokens": {
      "operator": "gte",
      "value": [100]
    }
  }
}

String Filters

Filter by customer identifier:

{
  "filters": {
    "customer_identifier": {
      "operator": "",
      "value": ["user@example.com"]
    }
  }
}

Filter by workflow name (prefix):

{
  "filters": {
    "workflow_name": {
      "operator": "startswith",
      "value": ["chat_"]
    }
  }
}

Multiple Filters

Combine multiple conditions:

{
  "filters": {
    "cost": {
      "operator": "gte",
      "value": [0.01]
    },
    "environment": {
      "operator": "",
      "value": ["production"]
    },
    "error_count": {
      "operator": "",
      "value": [0]
    }
  }
}

Metadata Filters

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

{
  "filters": {
    "metadata__user_id": {
      "operator": "",
      "value": ["user123"]
    }
  }
}

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"]
      }
    }
  }'