Skip to Content

Get span summary

POSThttps://api.respan.ai/api/request-logs/summary/

Returns aggregate span statistics for a time range. Send start_time, end_time, and environment as query parameters, and additional filters in the JSON body. Fields such as log_type are not read from query parameters. Empty or omitted filters may use pre-aggregated data; non-empty filters query individual spans using the List spans filter format.

Servers

https://api.respan.ai: Respan API Server

Authentication

RespanApiKey

Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.

HTTP scheme: bearer; format: Respan API key.

HTTP
Authorization: Bearer $RESPAN_API_KEY

Or:

DashboardJwt

Use a dashboard JWT only for dashboard-authenticated endpoints. Respan API-key endpoints use the respanApiKey auth field instead.

HTTP scheme: bearer; format: Dashboard JWT.

HTTP
Authorization: Bearer $RESPAN_DASHBOARD_JWT

Query parameters

Parameter Type Required Description and constraints
start_time string Optional
Start of time range (ISO 8601).
Format: date-time
Example: "2025-01-01T00:00:00Z"
end_time string Optional
End of time range (ISO 8601).
Format: date-time
Example: "2025-01-31T23:59:59Z"
environment string Optional
Filter by environment (prod or test).
Allowed: "prod", "test"
Example: "prod"

Request body

The request body is optional.

application/json

Field Type Requirement Description and constraints
$ object Optional body
-
filters object Optional
Each key is a field to filter on, and each value is a condition: {"<field>": {"operator": "<operator>", "value": [...]}}. A span must match every condition. To set two conditions on one field, such as a range, pass a list of conditions.

Operators: "" (equals, the default), not, in, not_in, lt, lte, gt, gte, contains, not_contains, icontains (ignores case), startswith, not_startswith, endswith, not_endswith, empty, not_empty. Put values in a list: "" and in match any of the listed values, and not and not_in match none of them. Other operators take one value; for empty and not_empty, send [""].

Fields:
- unique_id, trace_unique_id, span_unique_id, span_parent_id, span_name, span_workflow_name, thread_identifier, customer_identifier, customer_email, custom_identifier, group_identifier, evaluation_identifier, organization_key_id, prompt_id, prompt_name, prompt_version_number, model, provider_id, deployment_name, log_type, log_method, status, status_code, environment, error_class, error_code, error_message, error_fingerprint, cache_key, note
- True or false: stream, has_tool_calls, cache_bit, used_custom_credential, positive_feedback
- Numbers: cost, latency, time_to_first_token, tokens_per_second, routing_time, prompt_tokens, completion_tokens, total_request_tokens, prompt_cache_hit_tokens, prompt_cache_creation_tokens. The aliases total_cost, input_tokens, output_tokens and total_tokens also work, and so does trace_id for trace_unique_id.
- metadata__<key>: a custom metadata value. Values are strings, and spans without the key never match, even with not.
- scores__<evaluator_id>: an evaluator’s numeric score, with "", not, in, not_in, lt, lte, gt or gte.
- is_root_span ([true] or [false]), fault_domain (user, respan or provider), and behaviors (spans where the named behaviors fired, when span behaviors are on).

Unsupported fields return a 400 error.

Example:

json<br />{<br /> "customer_identifier": {"operator": "", "value": ["alex@acme.dev"]},<br /> "status_code": {"operator": "not", "value": [200]}<br />}<br />
Reference: #/components/schemas/Filters
Example: {"customer_identifier":{"operator":"","value":["alex@acme.dev"]}}
filters.status object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.status.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.status.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.status.value[] any Array item
-
filters.status_code object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.status_code.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.status_code.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.status_code.value[] any Array item
-
filters.unique_id object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.unique_id.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.unique_id.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.unique_id.value[] any Array item
-
filters.customer_identifier object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.customer_identifier.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.customer_identifier.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.customer_identifier.value[] any Array item
-
filters.thread_identifier object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.thread_identifier.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.thread_identifier.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.thread_identifier.value[] any Array item
-
filters.custom_identifier object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.custom_identifier.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.custom_identifier.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.custom_identifier.value[] any Array item
-
filters.group_identifier object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.group_identifier.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.group_identifier.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.group_identifier.value[] any Array item
-
filters.prompt_id object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.prompt_id.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.prompt_id.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.prompt_id.value[] any Array item
-
filters.trace_unique_id object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.trace_unique_id.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.trace_unique_id.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.trace_unique_id.value[] any Array item
-
filters.span_parent_id object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.span_parent_id.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.span_parent_id.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.span_parent_id.value[] any Array item
-
filters.is_root_span object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.is_root_span.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.is_root_span.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.is_root_span.value[] any Array item
-
filters.span_workflow_name object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.span_workflow_name.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.span_workflow_name.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.span_workflow_name.value[] any Array item
-
filters.span_name object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.span_name.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.span_name.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.span_name.value[] any Array item
-
filters.model object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.model.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.model.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.model.value[] any Array item
-
filters.log_type object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.log_type.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.log_type.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.log_type.value[] any Array item
-
filters.stream object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.stream.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.stream.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.stream.value[] any Array item
-
filters.has_tool_calls object Optional
Whether the span made tool calls.
Reference: #/components/schemas/FilterValue
filters.has_tool_calls.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.has_tool_calls.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.has_tool_calls.value[] any Array item
-
filters.cache_bit object Optional
Whether the response was served from the Respan cache.
Reference: #/components/schemas/FilterValue
filters.cache_bit.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.cache_bit.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.cache_bit.value[] any Array item
-
filters.cache_key object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.cache_key.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.cache_key.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.cache_key.value[] any Array item
-
filters.prompt_tokens object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.prompt_tokens.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.prompt_tokens.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.prompt_tokens.value[] any Array item
-
filters.completion_tokens object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.completion_tokens.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.completion_tokens.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.completion_tokens.value[] any Array item
-
filters.total_tokens object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.total_tokens.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.total_tokens.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.total_tokens.value[] any Array item
-
filters.cost object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.cost.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.cost.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.cost.value[] any Array item
-
filters.latency object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.latency.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.latency.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.latency.value[] any Array item
-
filters.positive_feedback object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.positive_feedback.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.positive_feedback.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.positive_feedback.value[] any Array item
-
filters.<key> object Map value
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.<key>.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.<key>.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.<key>.value[] any Array item
-

OpenAPI request schema

{
  "type": "object",
  "properties": {
    "filters": {
      "$ref": "#/components/schemas/Filters",
      "description": "Each key is a field to filter on, and each value is a condition: `{\"<field>\": {\"operator\": \"<operator>\", \"value\": [...]}}`. A span must match every condition. To set two conditions on one field, such as a range, pass a list of conditions.\n\n**Operators:** `\"\"` (equals, the default), `not`, `in`, `not_in`, `lt`, `lte`, `gt`, `gte`, `contains`, `not_contains`, `icontains` (ignores case), `startswith`, `not_startswith`, `endswith`, `not_endswith`, `empty`, `not_empty`. Put values in a list: `\"\"` and `in` match any of the listed values, and `not` and `not_in` match none of them. Other operators take one value; for `empty` and `not_empty`, send `[\"\"]`.\n\n**Fields:**\n- `unique_id`, `trace_unique_id`, `span_unique_id`, `span_parent_id`, `span_name`, `span_workflow_name`, `thread_identifier`, `customer_identifier`, `customer_email`, `custom_identifier`, `group_identifier`, `evaluation_identifier`, `organization_key_id`, `prompt_id`, `prompt_name`, `prompt_version_number`, `model`, `provider_id`, `deployment_name`, `log_type`, `log_method`, `status`, `status_code`, `environment`, `error_class`, `error_code`, `error_message`, `error_fingerprint`, `cache_key`, `note`\n- True or false: `stream`, `has_tool_calls`, `cache_bit`, `used_custom_credential`, `positive_feedback`\n- Numbers: `cost`, `latency`, `time_to_first_token`, `tokens_per_second`, `routing_time`, `prompt_tokens`, `completion_tokens`, `total_request_tokens`, `prompt_cache_hit_tokens`, `prompt_cache_creation_tokens`. The aliases `total_cost`, `input_tokens`, `output_tokens` and `total_tokens` also work, and so does `trace_id` for `trace_unique_id`.\n- `metadata__<key>`: a custom metadata value. Values are strings, and spans without the key never match, even with `not`.\n- `scores__<evaluator_id>`: an evaluator's numeric score, with `\"\"`, `not`, `in`, `not_in`, `lt`, `lte`, `gt` or `gte`.\n- `is_root_span` (`[true]` or `[false]`), `fault_domain` (`user`, `respan` or `provider`), and `behaviors` (spans where the named behaviors fired, when span behaviors are on).\n\nUnsupported fields return a 400 error.\n\n**Example:**\n\n```json\n{\n  \"customer_identifier\": {\"operator\": \"\", \"value\": [\"alex@acme.dev\"]},\n  \"status_code\": {\"operator\": \"not\", \"value\": [200]}\n}\n```"
    }
  }
}
No additional filters
JSON
{ "filters": {} }
Filter by span/log type
JSON
{ "filters": { "log_type": { "operator": "", "value": [ "chat" ] } } }

Responses

200

Summary statistics for matching spans.

application/json

Field Type Requirement Description and constraints
$ object Body
Example: {"number_of_requests":1,"total_cost":0,"total_tokens":0,"total_prompt_tokens":0,"total_completion_tokens":0,"avg_latency":0,"avg_tps":0,"avg_ttft":0,"scores":{}}
number_of_requests integer Required in parent
Total number of matching spans/log rows.
Example: 1024
total_cost number Required in parent
Total cost in USD for all matching spans/log rows.
Example: 12.45
total_tokens integer Required in parent
Total tokens across all matching spans/log rows.
Example: 150000
total_prompt_tokens integer Required in parent
Total prompt/input tokens.
Example: 80000
total_completion_tokens integer Required in parent
Total completion/output tokens.
Example: 70000
avg_latency number Required in parent
Average latency in seconds.
Example: 1.35
avg_tps number Required in parent
Average tokens per second.
Example: 45.2
avg_ttft number Required in parent
Average time to first token in seconds.
Example: 0.35
scores object Required in parent
Aggregated score summaries grouped by evaluator ID.
Additional properties are allowed
Example: {}

OpenAPI response schema

{
  "type": "object",
  "required": [
    "number_of_requests",
    "total_cost",
    "total_tokens",
    "total_prompt_tokens",
    "total_completion_tokens",
    "avg_latency",
    "avg_tps",
    "avg_ttft",
    "scores"
  ],
  "properties": {
    "number_of_requests": {
      "type": "integer",
      "description": "Total number of matching spans/log rows.",
      "example": 1024
    },
    "total_cost": {
      "type": "number",
      "description": "Total cost in USD for all matching spans/log rows.",
      "example": 12.45
    },
    "total_tokens": {
      "type": "integer",
      "description": "Total tokens across all matching spans/log rows.",
      "example": 150000
    },
    "total_prompt_tokens": {
      "type": "integer",
      "description": "Total prompt/input tokens.",
      "example": 80000
    },
    "total_completion_tokens": {
      "type": "integer",
      "description": "Total completion/output tokens.",
      "example": 70000
    },
    "avg_latency": {
      "type": "number",
      "description": "Average latency in seconds.",
      "example": 1.35
    },
    "avg_tps": {
      "type": "number",
      "description": "Average tokens per second.",
      "example": 45.2
    },
    "avg_ttft": {
      "type": "number",
      "description": "Average time to first token in seconds.",
      "example": 0.35
    },
    "scores": {
      "type": "object",
      "additionalProperties": true,
      "description": "Aggregated score summaries grouped by evaluator ID.",
      "example": {}
    }
  },
  "example": {
    "number_of_requests": 1,
    "total_cost": 0,
    "total_tokens": 0,
    "total_prompt_tokens": 0,
    "total_completion_tokens": 0,
    "avg_latency": 0,
    "avg_tps": 0,
    "avg_ttft": 0,
    "scores": {}
  }
}

400

Bad Request

application/json

Field Type Requirement Description and constraints
$ object Body
-
error string Optional
Error message
Example: "Invalid request body"

OpenAPI response schema

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Error message",
      "example": "Invalid request body"
    }
  }
}

403

The API key is missing, invalid or expired.

application/json

Field Type Requirement Description and constraints
$ object Body
-
detail string Required in parent
-

OpenAPI response schema

{
  "type": "object",
  "required": [
    "detail"
  ],
  "properties": {
    "detail": {
      "type": "string"
    }
  }
}
Example
JSON
{ "detail": "Your API key is invalid or expired, please check your API key in the platform settings." }

413

The query exceeded the service’s memory or execution-time limit. Narrow the time range or add filters before retrying.

application/json

Field Type Requirement Description and constraints
$ object Body
-
detail string Required in parent
-

OpenAPI response schema

{
  "type": "object",
  "required": [
    "detail"
  ],
  "properties": {
    "detail": {
      "type": "string"
    }
  }
}
Example
JSON
{ "detail": "This query is too large to run — it exceeded a per-query resource limit. Narrow the time range or add filters, then try again." }

429

Rate Limited

application/json

Field Type Requirement Description and constraints
$ object Body
-
error string Optional
Error message
Example: "Rate limit exceeded"

OpenAPI response schema

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Error message",
      "example": "Rate limit exceeded"
    }
  }
}

500

Internal Server Error

application/json

Field Type Requirement Description and constraints
$ object Body
-
error string Optional
Error message
Example: "Internal server error"

OpenAPI response schema

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Error message",
      "example": "Internal server error"
    }
  }
}

OpenAPI source

The operation and referenced components below retain the complete OpenAPI definitions, including constraints and examples.

OpenAPI operation

{
  "summary": "Get span summary",
  "operationId": "getSpansSummary",
  "tags": [
    "Spans"
  ],
  "description": "Returns aggregate span statistics for a time range. Send `start_time`, `end_time`, and `environment` as query parameters, and additional `filters` in the JSON body. Fields such as `log_type` are not read from query parameters. Empty or omitted `filters` may use pre-aggregated data; non-empty `filters` query individual spans using the List spans filter format.",
  "parameters": [
    {
      "name": "start_time",
      "in": "query",
      "schema": {
        "type": "string",
        "format": "date-time"
      },
      "description": "Start of time range (ISO 8601).",
      "example": "2025-01-01T00:00:00Z"
    },
    {
      "name": "end_time",
      "in": "query",
      "schema": {
        "type": "string",
        "format": "date-time"
      },
      "description": "End of time range (ISO 8601).",
      "example": "2025-01-31T23:59:59Z"
    },
    {
      "name": "environment",
      "in": "query",
      "schema": {
        "type": "string",
        "enum": [
          "prod",
          "test"
        ]
      },
      "description": "Filter by environment (`prod` or `test`).",
      "example": "prod"
    }
  ],
  "requestBody": {
    "required": false,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "filters": {
              "$ref": "#/components/schemas/Filters",
              "description": "Each key is a field to filter on, and each value is a condition: `{\"<field>\": {\"operator\": \"<operator>\", \"value\": [...]}}`. A span must match every condition. To set two conditions on one field, such as a range, pass a list of conditions.\n\n**Operators:** `\"\"` (equals, the default), `not`, `in`, `not_in`, `lt`, `lte`, `gt`, `gte`, `contains`, `not_contains`, `icontains` (ignores case), `startswith`, `not_startswith`, `endswith`, `not_endswith`, `empty`, `not_empty`. Put values in a list: `\"\"` and `in` match any of the listed values, and `not` and `not_in` match none of them. Other operators take one value; for `empty` and `not_empty`, send `[\"\"]`.\n\n**Fields:**\n- `unique_id`, `trace_unique_id`, `span_unique_id`, `span_parent_id`, `span_name`, `span_workflow_name`, `thread_identifier`, `customer_identifier`, `customer_email`, `custom_identifier`, `group_identifier`, `evaluation_identifier`, `organization_key_id`, `prompt_id`, `prompt_name`, `prompt_version_number`, `model`, `provider_id`, `deployment_name`, `log_type`, `log_method`, `status`, `status_code`, `environment`, `error_class`, `error_code`, `error_message`, `error_fingerprint`, `cache_key`, `note`\n- True or false: `stream`, `has_tool_calls`, `cache_bit`, `used_custom_credential`, `positive_feedback`\n- Numbers: `cost`, `latency`, `time_to_first_token`, `tokens_per_second`, `routing_time`, `prompt_tokens`, `completion_tokens`, `total_request_tokens`, `prompt_cache_hit_tokens`, `prompt_cache_creation_tokens`. The aliases `total_cost`, `input_tokens`, `output_tokens` and `total_tokens` also work, and so does `trace_id` for `trace_unique_id`.\n- `metadata__<key>`: a custom metadata value. Values are strings, and spans without the key never match, even with `not`.\n- `scores__<evaluator_id>`: an evaluator's numeric score, with `\"\"`, `not`, `in`, `not_in`, `lt`, `lte`, `gt` or `gte`.\n- `is_root_span` (`[true]` or `[false]`), `fault_domain` (`user`, `respan` or `provider`), and `behaviors` (spans where the named behaviors fired, when span behaviors are on).\n\nUnsupported fields return a 400 error.\n\n**Example:**\n\n```json\n{\n  \"customer_identifier\": {\"operator\": \"\", \"value\": [\"alex@acme.dev\"]},\n  \"status_code\": {\"operator\": \"not\", \"value\": [200]}\n}\n```"
            }
          }
        },
        "examples": {
          "empty": {
            "summary": "No additional filters",
            "value": {
              "filters": {}
            }
          },
          "log_type": {
            "summary": "Filter by span/log type",
            "value": {
              "filters": {
                "log_type": {
                  "operator": "",
                  "value": [
                    "chat"
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Summary statistics for matching spans.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "number_of_requests",
              "total_cost",
              "total_tokens",
              "total_prompt_tokens",
              "total_completion_tokens",
              "avg_latency",
              "avg_tps",
              "avg_ttft",
              "scores"
            ],
            "properties": {
              "number_of_requests": {
                "type": "integer",
                "description": "Total number of matching spans/log rows.",
                "example": 1024
              },
              "total_cost": {
                "type": "number",
                "description": "Total cost in USD for all matching spans/log rows.",
                "example": 12.45
              },
              "total_tokens": {
                "type": "integer",
                "description": "Total tokens across all matching spans/log rows.",
                "example": 150000
              },
              "total_prompt_tokens": {
                "type": "integer",
                "description": "Total prompt/input tokens.",
                "example": 80000
              },
              "total_completion_tokens": {
                "type": "integer",
                "description": "Total completion/output tokens.",
                "example": 70000
              },
              "avg_latency": {
                "type": "number",
                "description": "Average latency in seconds.",
                "example": 1.35
              },
              "avg_tps": {
                "type": "number",
                "description": "Average tokens per second.",
                "example": 45.2
              },
              "avg_ttft": {
                "type": "number",
                "description": "Average time to first token in seconds.",
                "example": 0.35
              },
              "scores": {
                "type": "object",
                "additionalProperties": true,
                "description": "Aggregated score summaries grouped by evaluator ID.",
                "example": {}
              }
            },
            "example": {
              "number_of_requests": 1,
              "total_cost": 0,
              "total_tokens": 0,
              "total_prompt_tokens": 0,
              "total_completion_tokens": 0,
              "avg_latency": 0,
              "avg_tps": 0,
              "avg_ttft": 0,
              "scores": {}
            }
          }
        }
      }
    },
    "400": {
      "description": "Bad Request",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "description": "Error message",
                "example": "Invalid request body"
              }
            }
          }
        }
      }
    },
    "403": {
      "$ref": "#/components/responses/InvalidApiKey"
    },
    "413": {
      "description": "The query exceeded the service's memory or execution-time limit. Narrow the time range or add filters before retrying.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "detail"
            ],
            "properties": {
              "detail": {
                "type": "string"
              }
            }
          },
          "example": {
            "detail": "This query is too large to run — it exceeded a per-query resource limit. Narrow the time range or add filters, then try again."
          }
        }
      }
    },
    "429": {
      "description": "Rate Limited",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "description": "Error message",
                "example": "Rate limit exceeded"
              }
            }
          }
        }
      }
    },
    "500": {
      "description": "Internal Server Error",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "description": "Error message",
                "example": "Internal server error"
              }
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "RespanApiKey": []
    },
    {
      "DashboardJwt": []
    }
  ]
}

OpenAPI path metadata

{}

Referenced OpenAPI components

{
  "responses": {
    "InvalidApiKey": {
      "description": "The API key is missing, invalid or expired.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "detail"
            ],
            "properties": {
              "detail": {
                "type": "string"
              }
            }
          },
          "example": {
            "detail": "Your API key is invalid or expired, please check your API key in the platform settings."
          }
        }
      }
    }
  },
  "schemas": {
    "FilterValue": {
      "type": "object",
      "description": "A filter condition with an operator and value.",
      "required": [
        "value"
      ],
      "properties": {
        "operator": {
          "type": "string",
          "description": "Comparison operator. An empty string means equals.",
          "enum": [
            "",
            "not",
            "in",
            "not_in",
            "lt",
            "lte",
            "gt",
            "gte",
            "contains",
            "not_contains",
            "icontains",
            "startswith",
            "not_startswith",
            "endswith",
            "not_endswith",
            "empty",
            "not_empty"
          ],
          "default": "",
          "example": "gte"
        },
        "value": {
          "type": "array",
          "description": "Value(s) to filter by.",
          "items": {},
          "example": [
            0.01
          ]
        }
      }
    },
    "Filters": {
      "type": "object",
      "description": "Each key is a field to filter on, and each value is a condition: `{\"<field>\": {\"operator\": \"<operator>\", \"value\": [...]}}`. A result must match every condition. To set two conditions on one field, such as a range, pass a list of conditions.\n\n**Operators:** `\"\"` (equals, the default), `not`, `in`, `not_in`, `lt`, `lte`, `gt`, `gte`, `contains`, `not_contains`, `icontains` (ignores case), `startswith`, `not_startswith`, `endswith`, `not_endswith`, `empty`, `not_empty`. Put values in a list: `\"\"` and `in` match any of the listed values, and `not` and `not_in` match none of them. Other operators take one value; for `empty` and `not_empty`, send `[\"\"]`.\n\nThe fields you can filter on depend on the endpoint; `metadata__<key>` filters custom metadata where the endpoint supports it.",
      "properties": {
        "status": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "status_code": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "unique_id": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "customer_identifier": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "thread_identifier": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "custom_identifier": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "group_identifier": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "prompt_id": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "trace_unique_id": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "span_parent_id": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "is_root_span": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "span_workflow_name": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "span_name": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "model": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "log_type": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "stream": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "has_tool_calls": {
          "$ref": "#/components/schemas/FilterValue",
          "description": "Whether the span made tool calls."
        },
        "cache_bit": {
          "$ref": "#/components/schemas/FilterValue",
          "description": "Whether the response was served from the Respan cache."
        },
        "cache_key": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "prompt_tokens": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "completion_tokens": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "total_tokens": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "cost": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "latency": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "positive_feedback": {
          "$ref": "#/components/schemas/FilterValue"
        }
      },
      "example": {
        "customer_identifier": {
          "operator": "",
          "value": [
            "alex@acme.dev"
          ]
        }
      },
      "additionalProperties": {
        "$ref": "#/components/schemas/FilterValue"
      }
    }
  },
  "securitySchemes": {
    "DashboardJwt": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "Dashboard JWT",
      "description": "Use a dashboard JWT only for dashboard-authenticated endpoints. Respan API-key endpoints use the respanApiKey auth field instead.",
      "x-fern-bearer": {
        "name": "dashboardJwt",
        "env": "RESPAN_DASHBOARD_JWT"
      }
    },
    "RespanApiKey": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "Respan API key",
      "description": "Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.",
      "x-fern-bearer": {
        "name": "respanApiKey",
        "env": "RESPAN_API_KEY"
      }
    }
  }
}