List spans

The Spans List endpoint allows you to retrieve past spans with specified filters.

Response fields

Each log in the response includes:

Universal fields (All Span Types)

input (string): JSON-serialized representation of the span’s input data
output (string): JSON-serialized representation of the span’s output data
log_type (string): Type of span ("chat", "embedding", "workflow", etc.)

Evaluation Scores

scores (object): Map of evaluator scores { evaluator_id: score_data }
- Each evaluator’s score includes:
  - evaluator_name (string): Name of the evaluator
  - evaluator_slug (string): Slug identifier for the evaluator
  - score_value (float): Numerical or boolean score value (booleans represented as 0.0 or 1.0)

Legacy compatibility

For log_type="chat", "completion", "text", or "response":

prompt_messages (array): Full input messages array (extracted from input)
completion_message (object): Full output message object (extracted from output)

For other span types (embedding, workflow, etc.), type-specific fields are extracted based on the log_type. See log types for details.

Query parameters

You can add these parameters to the URL query string. For example:

"https://api.respan.ai/api/request-logs/list/?page=1&sort_by=-id&is_test=false&all_envs=false&fetch_filters=false&page_size=1"

start_time

string

required

The start time for filtering spans in ISO 8601 format. If not provided, defaults to 1 hour ago.

Example

{
  "start_time": "2025-08-15T00:00:00" // ISO 8601 format
}

end_time

string

required

The end time for filtering spans in ISO 8601 format. If not provided, defaults to current time.

Example

{
  "end_time": "2025-08-16T00:00:00" // ISO 8601 format
}

sort_by

string

required

The field to sort by. Default is -id (same as sort by -timestamp, but with better performance). - is for descending order, if not provided, it will be in ascending order.

Properties

string

Sort by the ID of each request.

cost

string

Sort by the cost of each request.

time_to_first_token

string

TTFT - useful for Voice AI applications

latency

string

Generation time of each request.

prompt_tokens

string

Input / prompt tokens of each request.

completion_tokens

string

Output / completion tokens of each request.

all_tokens

string

Total tokens of each request.

scores__<evaluator_id>

string

Sort by evaluator score. Use the evaluator’s UUID as the suffix. Example: scores__d4f46e95-73ff-4166-8581-928c1a1b1589

Example

{
  "sort_by": "cost" //sort by cost in ascending order.
}

all_envs

string

default:"false"

Whether to include spans from all environments. is_test parameter will override this parameter. Options: true, false.

is_test

string

default:"false"

Whether the span is a test call or not. This parameter will override the all_envs parameter. Options: true, false.

fetch_filters

string

default:"false"

Whether to retrieve the available filtering options. Enabling this could slow down the response time. Options: true, false.

page_size

number

default:100

The number of spans to return per page. Maximum is 1000.

page

number

default:1

The page number of the current spans.

include_fields

string

Comma separated fields to be included in the response spans. This parameter allows you to specify which fields should be returned to improve performance and reduce response size.

include_fields guarantees the listed fields will be present in each span item, but it does not enforce exclusivity. The API may still return additional fields required for the endpoint (e.g., identifiers, pagination-related fields, or internal metadata).

Example

include_fields=custom_identifier,customer_identifier,id,latency

URL-based Filtering (Quick Filters)

You can filter spans directly via URL query parameters. This is useful for sharing filtered views, bookmarking, or building dynamic filter links.

Basic Syntax

Simple filtering:

?<field>=<value>

Advanced filtering with operators:

?<field>[value]=<value>&<field>[operator]=<operator>&<field>[connector]=<connector>

Parameters

[value]: The filter value (required)
[operator]: Comparison operator (optional, defaults to "" for equality)
- "" (empty): Exact match (is)
- "not": Not equal (is not)
[connector]: Logic connector (optional, defaults to "AND")
- "AND": Combine with previous filter using AND
- "OR": Combine with previous filter using OR

Field Auto-Detection

The system automatically detects how to handle each URL parameter:

Pagination/Sort parameters: Skipped (page, page_size, sort_by, etc.)
Metadata fields starting with “metadata__”: Filter custom metadata
Known span fields: Filter directly on that field
Unknown fields: Treated as custom metadata (auto-prefix “metadata__“)

Known span fields

These fields can be filtered directly without the metadata__ prefix:

Identifiers: customer_identifier, custom_identifier, thread_identifier, prompt_id, unique_id
Tracing: trace_unique_id, span_name, span_workflow_name
Provider/Model: model, deployment_name, provider_id
Status: status_code, status, error_message
Config: environment, log_type, stream, temperature, max_tokens
Metrics: cost, latency, tokens_per_second, time_to_first_token, prompt_tokens, completion_tokens, total_request_tokens

Map-type Fields (Double Underscore Prefix)

Custom metadata: metadata__<key> - Filter on custom metadata properties
Evaluator scores: scores__<evaluator_id> - Filter/sort by evaluation scores (see below)

URL Filter Examples

Filter by customer identifier

POST /api/request-logs/list/?customer_identifier=user_123

Filter with operator (status code not equal to 200)

POST /api/request-logs/list/?status_code[value]=200&status_code[operator]=not

Filter by custom metadata (auto-detected)

# This automatically becomes: metadata__event_id = "xxx"
POST /api/request-logs/list/?event_id=xxx

Explicit metadata filter

POST /api/request-logs/list/?metadata__user_type=premium

Multiple filters with OR logic

# (status_code = 200) OR (metadata__priority != "low")
POST /api/request-logs/list/?status_code[value]=200&status_code[connector]=OR&priority[value]=low&priority[operator]=not&priority[connector]=OR

Mixed known and unknown fields

# customer_identifier = "abc" AND metadata__event_id = "xxx" AND model = "gpt-4"
POST /api/request-logs/list/?customer_identifier=abc&event_id=xxx&model=gpt-4

Combining Multiple Filters

Multiple URL filters can be combined. All filters are joined with AND logic by default, or you can use the [connector] parameter for OR logic.

Example: Combined filters

# Filter by customer identifier AND status code
curl -X GET "https://api.respan.ai/api/request-logs/list/?customer_identifier=user_123&status_code=200&page_size=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Using operator syntax for advanced filtering
curl -X GET "https://api.respan.ai/api/request-logs/list/?customer_identifier=user_123&cost[value]=0.01&cost[operator]=gte" \
  -H "Authorization: Bearer YOUR_API_KEY"

Limitations

Simple ?field=value syntax supports only equality ("") and not-equal ("not") operators
For complex operators (gt, gte, lt, lte, contains, etc.), use the bracket syntax: ?field[value]=X&field[operator]=gt
Each field can only have one value in URL (no arrays)
All URL values are treated as strings

Sorting and Filtering by Evaluation Scores

You can sort and filter spans by evaluator scores using the scores__ prefix pattern (consistent with metadata__ filtering).

Sorting by Scores

# Sort by a specific evaluator (use evaluator_id from scores object)
?sort_by=-scores__abc-123-def-456  # Descending (highest scores first)
?sort_by=scores__abc-123-def-456   # Ascending (lowest scores first)

How to find your evaluator_id:

The evaluator_id is the key in the scores object returned in span responses
It’s the same as the UUID of the evaluator in your organization
Example: If your scores object has "d4f46e95-73ff-4166-8581-928c1a1b1589": {...}, use sort_by=-scores__d4f46e95-73ff-4166-8581-928c1a1b1589

Filtering by Scores

Use POST body filters to filter spans by score values:

Filter spans with score greater than 4.0

curl -X POST "https://api.respan.ai/api/request-logs/list/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "scores__abc-123-def-456": {
        "operator": "gt",
        "value": [4.0]
      }
    }
  }'

Filter spans with score less than or equal to 2.0

curl -X POST "https://api.respan.ai/api/request-logs/list/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "scores__abc-123-def-456": {
        "operator": "lte",
        "value": [2.0]
      }
    }
  }'

Supported operators for score filters:

"" (empty): Equal to
"gt": Greater than
"gte": Greater than or equal
"lt": Less than
"lte": Less than or equal
"not": Not equal to

Note: Score filtering and sorting leverage ClickHouse Map type indexes for efficient queries on large datasets.

Body parameters

You can add these parameters to the request body:

url = "https://api.respan.ai/api/request-logs/list/"
headers = {
    "Authorization": f"Bearer {YOUR_RESPAN_API_KEY}",
}
data = {
    "filters":    {
      "cost": {
        "operator": "gt",
        "value": [0.01]
      },
    }
}
response = requests.post(url, headers=headers, json=data)

filters

object

The filters to be applied to the spans. For available options in the response body, use the fetch_filters parameter.

If you want to filter your custom properties, you should add metadata__+ your custom property name. For example, if you want to filter your custom property my_custom_property, you should add metadata__my_custom_property to the filters.

Example

  {
    "name_of_metric": {
      "operator": "gt",
      "value": [100]
    },
  }

operator

string

required

Default is "" (equal).

For a complete list of filter operators and examples, see the Filters API Reference.

Properties

string

Equal

Example

{
  "name_of_metric": {
    "operator": "", // equal
    "value": [100]
  },
}

iexact

string

case insensitive equal

string

Less than

lte

string

Less than or equal

string

Greater than

gte

string

Greater than or equal

contains

string

Contains

endswith

string

Ends with

startswith

string

Starts with

string

Can be used in arrays or text

isnull

string

Check if the field is null

icontains

string

Case insensitive contains

not

string

Not equal

url = "https://api.respan.ai/api/request-logs/list/?page=1&sort_by=-id&is_test=false&all_envs=false&fetch_filters=false&page_size=1"


from urllib.parse import urlencode
params = {
    "page": 1,
    "sort_by": "-id",
    "is_test": "false",
    "all_envs": "false",
    "fetch_filters": "false",
    "page_size": 1
}
url = f"https://api.respan.ai/api/request-logs/list/?{urlencode(params)}"
headers = {
    "Authorization": f"Bearer {YOUR_RESPAN_API_KEY}",
}
data = {
    "filters": {}
}
response = requests.post(url, headers=headers, json=data)

{
    "count": 1250,
    "next": "https://api.respan.ai/api/request-logs/list/?page=2",
    "previous": null,
    "results": [
       {
        "unique_id": "xxxxx",
        "organization_key__name": "Respan Default",
        "organization": "Respan",
        "user": "hendrix@respan.ai",
        "is_example": false,
        "status": "success",
        "log_type": "chat",
        
        // Universal fields (all span types)
        "input": "[{\"role\":\"system\",\"content\":\"You are a helpful assistant\"},{\"role\":\"user\",\"content\":\"What is Respan?\"}]",
        "output": "{\"role\":\"assistant\",\"content\":\"Respan is a unified DevOps platform for AI products.\"}",
        
        // Type-specific fields (extracted from input/output for chat types)
        "prompt_messages": [
                {
                    "role": "system",
                    "content": "You are a helpful assistant"
                },
                {
                    "role": "user",
                    "content": "What is Respan?"
                }
        ],
        "completion_message": {
                "role": "assistant",
                "content": "Respan is a unified DevOps platform for AI products."
        },
        
        // Telemetry
        "prompt_tokens": 452,
        "completion_tokens": 89,
        "cost": 0.0005869,
        "latency": 1.2114145755767822,
        "time_to_first_token": null,
        "tokens_per_second": 73.4,
        "routing_time": 0.0,
        
        // Model info
        "model": "gpt-3.5-turbo",
        "foundation_model": "gpt-3.5-turbo",
        "provider_id": "openai",
        
        // Function calling
        "tool_choice": null,
        "tools": null,
        "tool_calls": null,
        
        // Metadata
        "timestamp": "2024-06-24T21:33:06.601353Z",
        "metadata": {
            // any custom params you passed
        },
        "customer_identifier": "123456",
        "customer_email": "",
        "thread_identifier": null,
        "custom_identifier": null,
        "trace_unique_id": null,
        
        // Evaluation Scores
        "scores": {
            "evaluator-id-123": {
                "evaluator_name": "Response Quality",
                "evaluator_slug": "response_quality",
                "score_value": 4.5
            }
        },
        
        // Status
        "failed": false,
        "stream": false,
        "status_code": 200,
        "used_custom_credential": false
       }
    ]
}

Observe

Develop

Evals

Manage

Automation

Reference

Response fields

Universal fields (All Span Types)

Evaluation Scores

Legacy compatibility

Query parameters

URL-based Filtering (Quick Filters)

Basic Syntax

Parameters

Field Auto-Detection

Known span fields

Map-type Fields (Double Underscore Prefix)

URL Filter Examples

Combining Multiple Filters

Limitations

Sorting and Filtering by Evaluation Scores

Sorting by Scores

Filtering by Scores

Body parameters

Observe

Develop

Evals

Manage

Automation

Reference

​Response fields

​Universal fields (All Span Types)

​Evaluation Scores

​Legacy compatibility

​Query parameters

​URL-based Filtering (Quick Filters)

​Basic Syntax

​Parameters

​Field Auto-Detection

​Known span fields

​Map-type Fields (Double Underscore Prefix)

​URL Filter Examples

​Combining Multiple Filters

​Limitations

​Sorting and Filtering by Evaluation Scores

​Sorting by Scores

​Filtering by Scores

​Body parameters

Response fields

Universal fields (All Span Types)

Evaluation Scores

Legacy compatibility

Query parameters

URL-based Filtering (Quick Filters)

Basic Syntax

Parameters

Field Auto-Detection

Known span fields

Map-type Fields (Double Underscore Prefix)

URL Filter Examples

Combining Multiple Filters

Limitations

Sorting and Filtering by Evaluation Scores

Sorting by Scores

Filtering by Scores

Body parameters