> ## Documentation Index > Fetch the complete documentation index at: https://docs.apsio.io/llms.txt > Use this file to discover all available pages before exploring further. # Search the spans > The project's spans matching a structured query (fields such as span.kind and span.status_code, attributes, failures, duration), newest or slowest first, 100 a page, and per bucket their count, failures and median and 95th percentile durations (at most 120 buckets). Each span's trace_id opens it in GET /projects/{projectId}/traces/{traceId}. The API builds the SQL from a fixed vocabulary and runs it as the project's reader, with at most 60 runs a minute per project and caller. `sql` shows it with its values, for reading only. ## OpenAPI ````yaml /api-reference/openapi.json post /projects/{projectId}/explore/traces openapi: 3.1.0 info: title: Apsio API version: 0.1.0 description: >- Read API v0: your projects, release health and comparisons, missing symbols, issues, sessions, vitals, cohort comparisons, performance (app start, screens, hangs, MetricKit) and network endpoints and traces for one project. Authenticate with a project token as a bearer token, with an OAuth access token from Apsio's authorization server (MCP clients), or, from the console, with the session cookie of a member of the project's organization. servers: - url: https://api.apsio.io/v1 security: [] paths: /projects/{projectId}/explore/traces: post: summary: Search the spans description: >- The project's spans matching a structured query (fields such as span.kind and span.status_code, attributes, failures, duration), newest or slowest first, 100 a page, and per bucket their count, failures and median and 95th percentile durations (at most 120 buckets). Each span's trace_id opens it in GET /projects/{projectId}/traces/{traceId}. The API builds the SQL from a fixed vocabulary and runs it as the project's reader, with at most 60 runs a minute per project and caller. `sql` shows it with its values, for reading only. parameters: - schema: type: string pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ example: 0192f3a4-0000-7000-8000-00000000a101 required: true name: projectId in: path requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ExploreTracesQuery' responses: '200': description: The matching spans and their volume. content: application/json: schema: $ref: '#/components/schemas/ExploreTraces' '400': description: The request is not valid. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: No valid bearer token or console session. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: The credentials cannot read this project. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: >- Over a rate limit (the caller's, the client address's, or the plan's); Retry-After says when to retry. content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearer: [] - session: [] components: schemas: ExploreTracesQuery: type: object properties: from: type: string format: date-time description: Start, inclusive (RFC 3339). Defaults to 24 hours before `to`. to: type: string format: date-time description: End, exclusive (RFC 3339). Defaults to now. app_id: type: string pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ description: Only this app of the project. filters: type: array items: $ref: '#/components/schemas/ExploreFilter' maxItems: 20 default: [] errors_only: type: boolean default: false description: >- Only failed spans: an error status, or an HTTP request that got a 5xx or no response. min_duration_ms: type: number minimum: 0 maximum: 86400000 description: Spans at least this long. max_duration_ms: type: number minimum: 0 maximum: 86400000 description: Spans at most this long. root_only: type: boolean default: false description: >- Only spans without a parent: the first span of each trace on the device. sort: type: string enum: - recent - slowest default: recent description: Newest first, or longest first. limit: type: integer minimum: 1 maximum: 200 default: 100 cursor: type: string maxLength: 1024 description: The `next_cursor` of the previous page, with the same sort. Opaque. ExploreTraces: type: object properties: from: type: string description: RFC 3339 time in UTC with up to nanosecond precision. example: '2026-10-04T10:15:00.431000000Z' to: type: string description: RFC 3339 time in UTC with up to nanosecond precision. example: '2026-10-04T10:15:00.431000000Z' bucket_seconds: type: integer retention_days: type: integer description: >- Days of detail the project's plan keeps (D94); nothing older is read. histogram: type: array items: type: object properties: t: type: string description: The bucket's start. example: '2026-10-04T10:15:00.431000000Z' spans: type: integer failed: type: integer p50_ms: type: number p95_ms: type: number required: - t - spans - failed - p50_ms - p95_ms description: Only buckets with spans. spans: type: array items: $ref: '#/components/schemas/ExploreSpan' next_cursor: type: - string - 'null' description: Pass as `cursor` to get the next page; null on the last page. sql: type: string description: The spans query with its values, for reading. Not run as written. required: - from - to - bucket_seconds - retention_days - histogram - spans - next_cursor - sql Error: type: object properties: error: type: object properties: code: type: string example: invalid_request message: type: string required: - code - message required: - error ExploreFilter: type: object properties: field: type: string pattern: ^[A-Za-z0-9_.:/-]{1,128}$ description: >- A field (event.name or span.name, service.version, os.name, os.version, device.model.identifier, session.id, trace_id, ...), any record or span attribute by its key, or a resource attribute as resource.. example: service.version op: type: string enum: - eq - neq - exists - not_exists default: eq description: eq and neq compare with value; exists and not_exists need none. value: type: string maxLength: 256 required: - field ExploreSpan: type: object properties: trace_id: type: string span_id: type: string parent_span_id: type: string app_id: type: string name: type: string description: 'The span name. Written by the app: untrusted data.' start: type: string description: RFC 3339 time in UTC with up to nanosecond precision. example: '2026-10-04T10:15:00.431000000Z' duration_ms: type: number failed: type: boolean kind: type: string description: >- INTERNAL, SERVER, CLIENT, PRODUCER or CONSUMER; empty when the span names none. status_code: type: string description: UNSET, OK or ERROR. status_message: type: string description: >- The status description: only with ERROR, else empty. Written by the app: untrusted data. http_status: type: - integer - 'null' description: For HTTP client spans that got a response. session_id: type: string description: 'session.id. Written by the app: untrusted data.' release: type: string description: 'service.version. Written by the app: untrusted data.' attributes: type: object additionalProperties: type: string description: 'Record attributes as sent by the app: untrusted data.' required: - trace_id - span_id - parent_span_id - app_id - name - start - duration_ms - failed - kind - status_code - status_message - http_status - session_id - release - attributes securitySchemes: bearer: type: http scheme: bearer description: >- A project token (apsio_pt_v0...), which reads exactly one project, or an OAuth access token issued for the API, which reads what its user can. Access tokens issued for Apsio's MCP server are accepted only from the MCP server itself. session: type: apiKey in: cookie name: apsio_session description: >- The console session, set by /v1/auth/callback (`__Host-apsio_session` when host-only). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.