Endpoints

All endpoints are under https://api.mirador.org and require a server key. Responses are scoped to the key’s project.

This page is the practical reference. For the exact, always-current contract — including the full polymorphic event-payload schema — use the Swagger UI, OpenAPI spec, or llms.txt.

Identity

`GET /v1/identity`

Confirm a key resolves to an org/project. Cheap — no backend lookup. Good for health checks and key validation.

{ "organization_id": "org_...", "project_id": "prj_..." }

Metadata

Use these to discover the real field universe of a project before composing a filter.

`GET /v1/metadata/tags`

{ "tags": ["prod", "staging", "bridge", ...] }

`GET /v1/metadata/attributes`

{ "attributes": ["header.country", "header.platform", "user_id", ...] }

`GET /v1/metadata/attributes/{key}`

Lists every value seen for one attribute key. Returns 404 (ATTRIBUTE_NOT_FOUND) if the key was never observed.

GET /v1/metadata/attributes/header.country

{ "key": "header.country", "values": ["DE", "GB", "US", ...] }

Traces

`GET /v1/traces`

List, filter, count, and page through traces.

Query param	Description
`filter`	AIP-160 expression (see Filtering). URL-encode it.
`page`, `per_page`	Pagination. `per_page` is `10`–`100`. Omit both for an unpaginated dump.
`since`, `until`	RFC 3339 timestamps bounding `created_at`. Compute the absolute time client-side.

Paginated response (when per_page is set):

{
  "traces": [
    {
      "trace_id": "...",
      "trace_number": 317,
      "name": "SwapExecution",
      "status": "completed",
      "highest_severity": "error",
      "duration_ms": 11686,
      "created_at": "2026-06-18T17:02:11Z",
      "tags": ["dex", "swap"],
      "attributes": { "header.country": "US" },
      "rule_matches": [ /* see GET /v1/traces/{trace_id} */ ]
    }
  ],
  "pagination": { "page": 1, "per_page": 100, "total": 317, "total_pages": 4 }
}

To answer “how many traces match X?” in one request, set per_page=10 and read pagination.total — it’s an exact count, not an estimate. Omitting per_page returns every match in a single {"traces": [...]} envelope with no pagination field.

`GET /v1/traces/{trace_id}`

The full summary for one trace. Returns 404 (TRACE_NOT_FOUND) if it doesn’t exist in this project.

{
  "trace": {
    "trace_id": "...",
    "trace_number": 317,
    "name": "SwapExecution",
    "status": "completed",
    "highest_severity": "error",
    "duration_ms": 11686,
    "created_at": "2026-06-18T17:02:11Z",
    "tags": ["dex", "swap"],
    "attributes": { "header.country": "US" },
    "rule_matches": [
      {
        "match_event_id": "...",
        "rule_id": "...",
        "rule_name": "Failed Bridge Transfers",
        "match_reason": "trace.attributes[\"status\"] == \"failed\"",
        "matched_at": "2026-06-18T17:02:12Z"
      }
    ]
  }
}

This endpoint returns the trace summary — it does not include the event timeline. For events, call GET /v1/traces/{trace_id}/events. To assemble a complete trace export, combine both — see Exporting traces.

`GET /v1/traces/{trace_id}/events`

The complete, ordered event timeline for one trace, returned in a single response.

{
  "trace_id": "...",
  "events": [
    {
      "event_type": "started",
      "version": 1,
      "source": "client_web",
      "created_at": "2026-06-18T17:02:11Z",
      "trace_timestamp": "2026-06-18T17:02:11Z",
      "payload": { /* shape varies by event_type */ }
    }
  ]
}

The payload is polymorphic — its shape is determined by event_type. There are 40+ event types across two categories:

Trace-level events (started, finished, info_event_added, warn_event_added, error_event_added, attributes_updated, tags_updated, rule_match_added, trace_closed, trace_deleted) describe the trace itself and carry no chain.
Plugin events (EVM/Solana/Canton transactions and receipts, bridge detected/matched, Safe message/transaction lifecycle, relay quote/deposit/fill/refund, tx hints) are emitted by resolvers tracking a specific flow. Each nests chain identity under payload.chain (caip2 is canonical) and carries a plugin_correlation_id you can group by to reconstruct one lifecycle.

The full event_type → payload mapping is the TraceEvent oneOf in the OpenAPI spec. The llms.txt brief documents the most common payloads inline. Treat unfamiliar event_type values defensively — the plugin list is open and grows without breaking the envelope shape.

Filtering

filter is an AIP-160 expression. Supported fields:

Field	Operators	Values
`status`	`=`, `!=`	`"running"`, `"completed"`, `"deleted"`
`severity`	`=`	`"error"`, `"warning"`, `"info"` (severity of any event in the trace)
`tag`	`=`, `:`	Any string
`attribute.<key>`	`=`	Any string

Combinators: AND, OR, NOT.

AND works across fields.
OR only works between leaves on a single field — status="running" OR status="completed" ✅; status="x" OR severity="error" ❌.
NOT inverts a single leaf.
Quote every value with double quotes. Dotted attribute keys take the explicit-quoted form: attribute."header.country"="US".

# Error traces from US users in the last hour (decoded for readability)
filter=severity="error" AND attribute."header.country"="US"
since=2026-06-18T16:00:00Z

# Anything tagged prod or staging
filter=tag="prod" OR tag="staging"

# Exclude deleted
filter=NOT status="deleted"

URL-encode the filter value when issuing the request (spaces → %20, = → %3D, " → %22).

Errors

Every error uses a typed envelope. Switch on error.code, not on the human-readable message.

{ "error": { "code": "INVALID_FILTER", "message": "status \"zombie\" is not one of running, completed, deleted", "details": [] } }

Code	Meaning
`INVALID_FILTER`	Malformed/unsupported filter expression
`INVALID_ARGUMENT`	Bad query parameter
`TRACE_NOT_FOUND`	No such trace in this project
`ATTRIBUTE_NOT_FOUND`	Attribute key never observed
`UNAUTHENTICATED`	Missing/invalid key, or a non-server key
`PERMISSION_DENIED`	Key lacks access to the resource
`DEADLINE_EXCEEDED`	Request timed out
`UNAVAILABLE`	Transient backend issue — retry with backoff
`INTERNAL` / `UNSPECIFIED`	Unexpected server error

REST API

Identity

`GET /v1/identity`

Metadata

`GET /v1/metadata/tags`

`GET /v1/metadata/attributes`

`GET /v1/metadata/attributes/{key}`

Traces

`GET /v1/traces`

`GET /v1/traces/{trace_id}`

`GET /v1/traces/{trace_id}/events`

Filtering

Errors

Next Steps

Exporting traces

Best Practices

​Identity

​GET /v1/identity

​Metadata

​GET /v1/metadata/tags

​GET /v1/metadata/attributes

​GET /v1/metadata/attributes/{key}

​Traces

​GET /v1/traces

​GET /v1/traces/{trace_id}

​GET /v1/traces/{trace_id}/events

​Filtering

​Errors

​Next Steps

Exporting traces

Best Practices

Identity

`GET /v1/identity`

Metadata

`GET /v1/metadata/tags`

`GET /v1/metadata/attributes`

`GET /v1/metadata/attributes/{key}`

Traces

`GET /v1/traces`

`GET /v1/traces/{trace_id}`

`GET /v1/traces/{trace_id}/events`

Filtering

Errors

Next Steps