> ## Documentation Index > Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt > Use this file to discover all available pages before exploring further. # List traces > Returns one summary per distinct trace_id, newest-first. Keyset pagination on (start_time, trace_id). `from` and `to` are required; the window must be at most 31 days. Requires `telemetry:ReadTraces`. ## OpenAPI ````yaml /api-reference/specs/telemetry.yaml get /v1/traces openapi: 3.0.3 info: title: Basaltic Telemetry API version: 1.0.0 description: | Regional telemetry API — log groups + log ingest/search, ClickHouse metrics (remote_write + structured query with Prometheus-compatible JSON envelopes), span ingest, and trace search/detail + per-account trace settings. contact: name: Basaltic Support email: ping@basaltic.sh license: name: Proprietary url: https://basaltic.sh/terms servers: - url: https://telemetry.{region}.basaltic.sh description: Regional API endpoint (one per region) variables: region: default: sa-saopaulo-1 description: Region code security: - SignatureAuth: [] paths: /v1/traces: get: tags: - Telemetry summary: List traces description: | Returns one summary per distinct trace_id, newest-first. Keyset pagination on (start_time, trace_id). `from` and `to` are required; the window must be at most 31 days. Requires `telemetry:ReadTraces`. operationId: searchTraces parameters: - name: from in: query required: true description: Lower bound on span start_time (inclusive) schema: type: string format: date-time example: '2026-01-15T00:00:00Z' - name: to in: query required: true description: >- Upper bound on span start_time (exclusive); must be after from and within 31d schema: type: string format: date-time example: '2026-01-16T00:00:00Z' - name: service in: query description: Filter by service.name schema: type: string example: api-gateway - name: operation in: query description: Filter by span name (operation) schema: type: string example: GET /api/users - name: status_code in: query description: Filter by status code schema: type: string enum: - UNSET - OK - ERROR example: ERROR - name: min_duration_ms in: query description: Filter to traces whose end-to-end duration is at least this many ms schema: type: number format: double minimum: 0 example: 100 - $ref: '#/components/parameters/LimitDefault50' - $ref: '#/components/parameters/Marker' responses: '200': description: Page of trace summaries content: application/json: schema: $ref: '#/components/schemas/TraceListResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalServerError' components: parameters: LimitDefault50: name: limit in: query description: >- Maximum number of items to return. A value above the maximum is clamped to it rather than rejected, so a page shorter than the one you asked for is normal — page until `meta.has_more` is false, not until a page looks short. required: false schema: type: integer minimum: 1 maximum: 100 default: 50 example: 50 Marker: name: marker in: query description: >- Opaque pagination cursor. Echo back the `meta.marker` value from the previous page to fetch the next one; do not construct or parse it. The token's internal form varies by endpoint (a resource ID, a timestamp, …) and is not guaranteed stable across releases. required: false schema: type: string example: 550e8400-e29b-41d4-a716-446655440000 schemas: TraceListResponse: type: object properties: traces: type: array items: $ref: '#/components/schemas/TraceSummary' meta: $ref: '#/components/schemas/PaginationMeta' TraceSummary: type: object properties: trace_id: type: string example: 4bf92f3577b34da6a3ce929d0e0e4736 root_span_id: type: string example: 00f067aa0ba902b7 root_name: type: string example: GET /api/users root_service: type: string example: api-gateway start_time: type: string format: date-time example: '2026-01-15T09:30:00Z' duration_ms: type: number format: double example: 12.4 span_count: type: integer example: 18 error_count: type: integer example: 0 service_count: type: integer example: 4 PaginationMeta: type: object properties: total: type: integer description: Total number of items example: 150 limit: type: integer description: Number of items per page example: 20 marker: type: string description: >- Opaque cursor for the next page. Pass it back as the `marker` query parameter; treat it as a token, not a value to parse. example: 550e8400-e29b-41d4-a716-446655440000 has_more: type: boolean description: Whether there are more items example: true Error: type: object required: - error properties: error: type: object required: - code - message - request_id properties: code: type: string description: Error code identifying the type of error example: INVALID_INPUT message: type: string description: Human-readable error message example: Invalid request parameters request_id: type: string format: uuid description: Request ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 responses: BadRequest: description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INVALID_INPUT message: Invalid request parameters request_id: 550e8400-e29b-41d4-a716-446655440000 Unauthorized: description: Authentication required or token invalid content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UNAUTHORIZED message: Authentication required request_id: 550e8400-e29b-41d4-a716-446655440000 Forbidden: description: Insufficient permissions content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ACCESS_DENIED message: You don't have permission to perform this action request_id: 550e8400-e29b-41d4-a716-446655440000 InternalServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INTERNAL_ERROR message: An internal error occurred request_id: 550e8400-e29b-41d4-a716-446655440000 securitySchemes: SignatureAuth: type: apiKey in: header name: Authorization description: > Request signing with an access key issued to a service account. An HMAC-SHA256 over a canonical form of the request, close to AWS SigV4. The `basaltic` CLI signs for you. Send `Authorization`, `X-Date` (UTC, `YYYYMMDDTHHMMSSZ`) and `X-Nonce` (random per request); add `X-Content-Sha256` to bind a body, and `X-Amz-Security-Token` when using temporary credentials. ``` Authorization: BASALTIC-HMAC-SHA256 Credential=///basaltic/basaltic_request, SignedHeaders=host;x-date;x-nonce, Signature= ``` `` is the region code you are calling, or `global` for the global services. A signature is valid for 5 minutes from `X-Date`, and mutating requests are replay-guarded on the nonce. **Full signing procedure, including a working implementation:** https://docs.basaltic.sh/authentication ## Rate limits There is no global request budget. A limit applies only where an operation documents a `429`, and that operation says what it counts. Those responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and, on a `429`, `Retry-After` — read them rather than hard-coding a number. Retrying before `Retry-After` is refused and extends the window. Everything else is bounded by quota, not by request rate. ````