> ## Documentation Index > Fetch the complete documentation index at: https://puzzlet-9ba7bb98.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Search spans > Search spans with structured JSON filters — the programmatic form of the `filter` string DSL on `GET /v1/spans`. `filters` is an AND-list of predicates (`{field, operator, value}`) and one-level OR-groups (`{or: [...]}`). Adds membership operators `in`, `notIn`, and `between`. Valid fields and operators are machine-readable at `GET /v1/filter-schema`. Defaults to the last 7 days when `start_date` is unset; the maximum search window is 90 days. ## OpenAPI ````yaml /openapi.yaml post /v1/spans/search 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: >- Eval trial-result ingest: per-trial score rows plus full-fidelity artifact blobs. name: Evals - 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: 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: Per-app named environments (e.g. `dev`, `prod`). CRUD for env lifecycle. 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: >- Cloud workers — terminal coding agents on managed compute. Launch one-shot runs or persistent multi-turn sessions against the app's connected repo; every response carries the dashboard deep link to the live thread. name: Workers - description: Service health checks. name: Health paths: /v1/spans/search: post: tags: - Spans summary: Search spans description: >- Search spans with structured JSON filters — the programmatic form of the `filter` string DSL on `GET /v1/spans`. `filters` is an AND-list of predicates (`{field, operator, value}`) and one-level OR-groups (`{or: [...]}`). Adds membership operators `in`, `notIn`, and `between`. Valid fields and operators are machine-readable at `GET /v1/filter-schema`. Defaults to the last 7 days when `start_date` is unset; the maximum search window is 90 days. operationId: search-spans requestBody: content: application/json: schema: additionalProperties: false properties: end_date: format: date-time type: string filters: items: anyOf: - additionalProperties: false properties: field: maxLength: 128 minLength: 1 type: string operator: enum: - equals - notEquals - contains - notContains - startsWith - endsWith - gt - gte - lt - lte - exists - doesNotExist - in - notIn - between type: string value: anyOf: - maxLength: 500 type: string - type: number - items: anyOf: - maxLength: 500 type: string - type: number maxItems: 50 type: array required: - field - operator type: object - additionalProperties: false properties: or: items: additionalProperties: false properties: field: maxLength: 128 minLength: 1 type: string operator: enum: - equals - notEquals - contains - notContains - startsWith - endsWith - gt - gte - lt - lte - exists - doesNotExist - in - notIn - between type: string value: anyOf: - maxLength: 500 type: string - type: number - items: anyOf: - maxLength: 500 type: string - type: number maxItems: 50 type: array required: - field - operator type: object minItems: 1 type: array required: - or type: object maxItems: 20 type: array limit: default: 50 maximum: 1000 minimum: 1 type: integer offset: default: 0 minimum: 0 type: integer start_date: format: date-time type: string type: object responses: '200': content: application/json: schema: properties: data: items: properties: cost: type: number duration_ms: type: number id: type: string input_tokens: minimum: 0 type: integer metadata: additionalProperties: type: string type: object model: nullable: true type: string name: type: string output_tokens: minimum: 0 type: integer parent_id: nullable: true type: string prompt_name: nullable: true type: string service_name: type: string span_kind: type: string status: enum: - UNSET - OK - ERROR type: string status_message: type: string timestamp: format: date-time type: string tokens: minimum: 0 type: integer trace_id: type: string type: type: string required: - id - trace_id - parent_id - name - status - status_message - duration_ms - timestamp - type - model - input_tokens - output_tokens - tokens - cost - span_kind - service_name - prompt_name - metadata 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 matching spans. '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 filters or time window. '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 ````