> ## Documentation Index > Fetch the complete documentation index at: https://docs.agentmark.co/llms.txt > Use this file to discover all available pages before exploring further. # List traces > Retrieve a paginated list of traces. Supports filtering by status, user, model, and date range. ## OpenAPI ````yaml /openapi.yaml get /v1/traces openapi: 3.0.3 info: contact: email: hello@agentmark.co url: https://docs.agentmark.co description: >- The AgentMark Gateway API lets you ingest traces, create scores, and retrieve prompt templates programmatically. Most developers should use the [AgentMark SDK](/introduction/overview) for integration. The REST API is for cases where you need direct HTTP access or are building a custom integration. Versioning: every endpoint is prefixed with `/v1/`. Breaking changes ship under a new version prefix (`/v2/`, etc.) with a 90-day-minimum deprecation window — see [API versioning & stability](/api-reference/versioning) for the full policy on what constitutes a breaking vs. additive change. title: AgentMark Gateway API version: '1.0' servers: - description: Production (AgentMark Cloud) url: https://api.agentmark.co - description: Local dev server (`npx @agentmark-ai/cli dev`) url: http://localhost:9418 security: - AppId: [] BearerAuth: [] tags: - description: Ingest, query, and export OpenTelemetry trace data. name: Traces - description: >- Coding-agent session ingest (outerlayer sync) and content-addressed session images. name: Agents - description: Query individual spans across traces. name: Spans - description: Create, retrieve, list, and delete score records for spans and traces. name: Scoring - description: Structured-filter search across observability resources. name: Search - description: Retrieve the effective synced project configuration. name: Config - description: List and retrieve datasets. name: Datasets - description: Query server feature availability. name: Capabilities - description: Per-model LLM pricing data. Public, unauthenticated. name: Pricing - description: >- Create, list, and revoke tenant API keys. Plaintext returned exactly once at creation. name: API Keys - description: >- List and retrieve score configuration definitions from the synced project config. name: Score Configs - description: >- Trigger and inspect managed deployments. POST returns 202; deployments run asynchronously and progress is observed via GET. name: Deployments - description: >- Per-app named environments (e.g. `dev`, `prod`). CRUD for env lifecycle; promote/rollback routes land alongside in this group as feature 054 lands the saga. name: Environments - description: >- App CRUD — the top-level tenant entity every other resource hangs off. Lets a headless agent provision an app without the dashboard. name: Apps - description: Service health checks. name: Health paths: /v1/traces: get: tags: - Traces summary: List traces description: >- Retrieve a paginated list of traces. Supports filtering by status, user, model, and date range. operationId: list-traces parameters: - in: query name: limit required: false schema: default: 50 maximum: 1000 minimum: 1 type: integer - in: query name: offset required: false schema: default: 0 minimum: 0 nullable: true type: integer - in: query name: start_date required: false schema: format: date type: string - in: query name: end_date required: false schema: format: date type: string - in: query name: sort_by required: false schema: type: string - in: query name: sort_order required: false schema: enum: - asc - desc type: string - in: query name: status required: false schema: enum: - OK - ERROR type: string - in: query name: user_id required: false schema: type: string - in: query name: model required: false schema: type: string - in: query name: dataset_run_id required: false schema: type: string - in: query name: session_id required: false schema: type: string - in: query name: name required: false schema: type: string - in: query name: tag required: false schema: anyOf: - type: string - items: type: string type: array - in: query name: commit_sha required: false schema: type: string - description: >- Filter expression (string DSL). Clauses combined with `and`; a clause is a predicate (`field operator [value]`) or a parenthesized OR-group of predicates: `(a = 1 or b = 2)`. `or` only inside parens, `and` only outside; groups do not nest. Operators: `=`, `!=`, `>`, `>=`, `<`, `<=`, `contains`, `not contains`, `starts with`, `ends with`, and (for `metadata.`) `exists` / `does not exist`. Quote values with spaces. Fields: model, user_id, session_id, trace_id, prompt_name, input, output, props, semantic_kind, latency_ms, cost, prompt_tokens, completion_tokens, status (OK|ERROR), tags, metadata., score__. Example: `(model = "gpt-4o" or model = "o3") and status = ERROR`. Malformed filters return 400. in: query name: filter required: false schema: description: >- Filter expression (string DSL). Clauses combined with `and`; a clause is a predicate (`field operator [value]`) or a parenthesized OR-group of predicates: `(a = 1 or b = 2)`. `or` only inside parens, `and` only outside; groups do not nest. Operators: `=`, `!=`, `>`, `>=`, `<`, `<=`, `contains`, `not contains`, `starts with`, `ends with`, and (for `metadata.`) `exists` / `does not exist`. Quote values with spaces. Fields: model, user_id, session_id, trace_id, prompt_name, input, output, props, semantic_kind, latency_ms, cost, prompt_tokens, completion_tokens, status (OK|ERROR), tags, metadata., score__. Example: `(model = "gpt-4o" or model = "o3") and status = ERROR`. Malformed filters return 400. type: string responses: '200': content: application/json: schema: properties: data: items: properties: cost: type: number end: format: date-time type: string id: type: string input_preview: nullable: true type: string latency_ms: type: number name: type: string output_preview: nullable: true type: string span_count: minimum: 0 type: integer start: format: date-time type: string status: enum: - UNSET - OK - ERROR type: string tags: items: type: string type: array tokens: minimum: 0 type: integer required: - id - name - status - start - end - latency_ms - cost - tokens - span_count type: object type: array pagination: properties: limit: minimum: 0 type: integer offset: minimum: 0 type: integer total: minimum: 0 type: integer required: - total - limit - offset type: object required: - data - pagination type: object description: A paginated list of traces. '400': content: application/json: schema: properties: error: properties: code: type: string message: type: string required: - code - message type: object required: - error type: object description: Invalid query parameters. '401': content: application/json: schema: properties: error: properties: code: type: string message: type: string required: - code - message type: object required: - error type: object description: Missing or invalid API key. '429': content: application/json: schema: properties: error: properties: code: type: string message: type: string required: - code - message type: object required: - error type: object description: Rate limited. components: securitySchemes: AppId: description: >- Application ID for tenant scoping. X-Outerlayer-App-Id is accepted as an equivalent header. in: header name: X-Agentmark-App-Id type: apiKey BearerAuth: description: API key (sk_agentmark_*) scheme: bearer type: http ````