> ## Documentation Index > Fetch the complete documentation index at: https://docs.gp.scale.com/llms.txt > Use this file to discover all available pages before exploring further. # Search spans > Search and list spans matching a set of filters, returning a keyset-paginated page. Filters in the request body include trace and span ids, names, statuses, types, free-text search, metadata, duration bounds, and more, scoped to an optional time window. Results are keyset-paginated on indexed columns rather than offset-paginated, and ``total`` is not computed (it is always 0); use the pagination cursors to page through results. Reads route to Postgres or the ClickHouse-backed tracing service per account (with Postgres fallback outside strict mode), and results are narrowed to traces the caller is authorized to read — a filter that resolves to no authorized traces yields an empty page rather than an error. A reversed time window (``from_ts`` after ``to_ts``) is rejected with 422, as is a request whose combined ``trace_ids``, ``span_ids``, ``excluded_span_ids``, ``excluded_trace_ids``, and ``parent_ids`` count exceeds 10000. ## OpenAPI ````yaml https://api.sgp.scale.com/openapi-versions/v5/openapi.json post /v5/spans/search openapi: 3.1.0 info: title: EGP API V5 description: >- This is the parent API for all EGP APIs. If you are looking for the EGP API, please go to https://api.egp.scale.com/docs. contact: name: Scale Generative AI Platform url: https://scale.com/genai-platform version: 0.1.0 servers: - url: https://api.egp.scale.com security: [] paths: /v5/spans/search: post: tags: - Spans summary: Search spans description: >- Search and list spans matching a set of filters, returning a keyset-paginated page. Filters in the request body include trace and span ids, names, statuses, types, free-text search, metadata, duration bounds, and more, scoped to an optional time window. Results are keyset-paginated on indexed columns rather than offset-paginated, and ``total`` is not computed (it is always 0); use the pagination cursors to page through results. Reads route to Postgres or the ClickHouse-backed tracing service per account (with Postgres fallback outside strict mode), and results are narrowed to traces the caller is authorized to read — a filter that resolves to no authorized traces yields an empty page rather than an error. A reversed time window (``from_ts`` after ``to_ts``) is rejected with 422, as is a request whose combined ``trace_ids``, ``span_ids``, ``excluded_span_ids``, ``excluded_trace_ids``, and ``parent_ids`` count exceeds 10000. operationId: POST-V5-/v5/spans/search parameters: - name: starting_after in: query required: false schema: anyOf: - type: string - type: 'null' title: Starting After - name: ending_before in: query required: false schema: anyOf: - type: string - type: 'null' title: Ending Before - name: limit in: query required: false schema: type: integer maximum: 10000 minimum: 1 default: 100 title: Limit - name: sort_by in: query required: false schema: anyOf: - type: string - type: 'null' title: Sort By - name: sort_order in: query required: false schema: anyOf: - $ref: '#/components/schemas/SortOrder' - type: 'null' default: asc title: Sort Order - name: from_ts in: query required: false schema: anyOf: - type: string format: date-time - type: 'null' description: The starting (oldest) timestamp in ISO format. title: From Ts description: The starting (oldest) timestamp in ISO format. - name: to_ts in: query required: false schema: anyOf: - type: string format: date-time - type: 'null' description: The ending (most recent) timestamp in ISO format. title: To Ts description: The ending (most recent) timestamp in ISO format. - name: x-selected-account-id in: header required: false schema: anyOf: - type: string - type: 'null' title: Account ID Header requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TracesSearchRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/SpanSearchPage' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyHeader: [] components: schemas: SortOrder: type: string enum: - asc - desc title: SortOrder TracesSearchRequest: properties: parents_only: title: Parents Only description: Only fetch spans that are the top-level (ie. have no parent_id) type: boolean span_ids: title: Span Ids description: Filter by span IDs items: type: string type: array trace_ids: title: Trace Ids description: >- Filter by trace IDs. The combined count of trace_ids, span_ids, excluded_span_ids, excluded_trace_ids, and parent_ids may not exceed 10000. A request over that returns 422. items: type: string type: array excluded_span_ids: title: Excluded Span Ids description: List of span IDs to exclude from results items: type: string type: array excluded_trace_ids: title: Excluded Trace Ids description: List of trace IDs to exclude from results items: type: string type: array group_id: title: Group Id description: Filter by group ID type: string parent_ids: title: Parent Ids description: Filter to the direct children of any of these parent span IDs items: type: string type: array names: title: Names description: Filter by trace/span name items: type: string type: array statuses: title: Statuses description: Filter on span status items: $ref: '#/components/schemas/ApplicationOperationStatus' type: array types: title: Types items: $ref: '#/components/schemas/ApplicationOperationType' type: array search_texts: title: Search Texts description: >- Case-insensitive substring search across span name, input, output, and metadata (no tokenization or stemming). Multiple terms are ANDed, and UUID-shaped terms match trace IDs instead. Substring means mid-word fragments match, while an inflected form such as a plural matches only where it appears literally. A span must match every non-UUID term, and each term may match any of the searched fields. UUID matches are ORed onto the text match. Each term must be at least 2 characters. For exact trace ID lookup, use the `trace_ids` filter. Accounts still served by the legacy trace store match differently until migrated: terms match as stemmed whole words rather than substrings, only input and output are searched, the 2-character minimum is not enforced, and characters like `:`, `|`, or `!` inside a term may be interpreted as query operators or cause an error. items: type: string type: array extra_metadata: title: Extra Metadata description: Filter on custom metadata key-value pairs additionalProperties: true type: object application_variant_ids: title: Application Variant Ids description: Filter by application variant IDs items: type: string type: array assessment_types: title: Assessment Types description: Filter to spans that have at least one assessment of these types items: type: string type: array acp_types: title: Acp Types description: Filter by ACP types items: type: string type: array agentex_agent_names: title: Agentex Agent Names description: Filter by Agentex agent names items: type: string type: array agentex_agent_ids: title: Agentex Agent Ids description: Filter by Agentex agent IDs items: type: string type: array min_duration_ms: title: Min Duration Ms description: >- Minimum span duration in milliseconds (inclusive). An in-flight span with no end time has no known duration and is treated as unbounded, so it matches every minimum. type: integer max_duration_ms: title: Max Duration Ms description: >- Maximum span duration in milliseconds (inclusive). An in-flight span with no end time has no known duration and is treated as unbounded, so it never falls within a maximum and is excluded. type: integer type: object title: TracesSearchRequest SpanSearchPage: properties: object: type: string const: list title: Object default: list items: items: $ref: '#/components/schemas/Span' type: array title: Items limit: type: integer title: Limit description: The maximum number of items to return. default: 100 total: type: integer title: Total description: >- The total of items that match the query. This is greater than or equal to the number of items returned. has_more: type: boolean title: Has More description: Whether there are more items left to be fetched. next_cursor: title: Next Cursor description: >- Pass as starting_after to fetch the next page. None when there is no next page. type: string prev_cursor: title: Prev Cursor description: >- Pass as ending_before to fetch the previous page. None when on the first page. type: string window_truncated: title: Window Truncated description: >- True when the requested window exceeded the 90 day maximum and was clamped, so results cover only effective_from_ts..effective_to_ts. null when no clamp occurred. type: boolean effective_from_ts: title: Effective From Ts description: Resolved start of the searched window. null when no clamp occurred. type: string format: date-time effective_to_ts: title: Effective To Ts description: Resolved end of the searched window. null when no clamp occurred. type: string format: date-time type: object required: - items - total - has_more description: >- Span search page carrying sgp-traces' opaque pagination cursors. The Postgres path keyset-paginates on the span id and leaves these unset. The ClickHouse path returns opaque cursors that clients must round-trip. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ApplicationOperationStatus: type: string enum: - SUCCESS - ERROR - CANCELED title: ApplicationOperationStatus ApplicationOperationType: type: string enum: - TEXT_INPUT - TEXT_OUTPUT - COMPLETION_INPUT - COMPLETION - KB_RETRIEVAL - KB_INPUT - RERANKING - EXTERNAL_ENDPOINT - PROMPT_ENGINEERING - DOCUMENT_INPUT - MAP_REDUCE - DOCUMENT_SEARCH - DOCUMENT_PROMPT - CUSTOM - CODE_EXECUTION - DATA_MANIPULATION - EVALUATION - FILE_RETRIEVAL - KB_ADD_CHUNK - KB_MANAGEMENT - GUARDRAIL - OUTPUT_GUARDRAIL - TRACER - AGENT_TRACER - AGENT_WORKFLOW - STANDALONE title: ApplicationOperationType Span: properties: id: type: string title: Id object: type: string const: span title: Object default: span created_by: $ref: '#/components/schemas/Identity' description: The identity that created the entity. name: type: string title: Name trace_id: type: string maxLength: 256 title: Trace Id description: id for grouping traces together, uuid is recommended parent_id: title: Parent Id description: Reference to a parent span_id type: string group_id: title: Group Id description: Reference to a group_id type: string start_timestamp: type: string format: date-time title: Start Timestamp end_timestamp: title: End Timestamp type: string format: date-time input: title: Input additionalProperties: true type: object output: title: Output additionalProperties: true type: object metadata: title: Metadata additionalProperties: true type: object expected: title: Expected additionalProperties: true type: object status: $ref: '#/components/schemas/ApplicationOperationStatus' default: SUCCESS type: $ref: '#/components/schemas/ApplicationOperationType' default: STANDALONE application_interaction_id: title: Application Interaction Id description: The interaction ID this span belongs to type: string application_variant_id: title: Application Variant Id description: The id of the application variant this span belongs to type: string account_id: type: string title: Account Id type: object required: - id - name - trace_id - start_timestamp - account_id ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: title: Error Type type: string input: title: Input ctx: type: object title: Context additionalProperties: true type: object required: - loc - msg - type title: ValidationError Identity: properties: id: type: string title: Id object: type: string const: identity title: Object default: identity type: $ref: '#/components/schemas/IdentityType' type: object required: - id - type title: Identity IdentityType: type: string enum: - user - service_account title: IdentityType securitySchemes: APIKeyHeader: type: apiKey in: header name: x-api-key ````