API reference

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.

​

Base URL

https://api.agentmark.co

http://localhost:9418

• Both surfaces: /v1/config, /v1/traces (ingest + read), /v1/sessions, /v1/spans, /v1/scores (full CRUD + batch), /v1/datasets, /v1/experiments, /v1/templates, /v1/capabilities, /v1/pricing.
• Cloud-only (local returns 404 or a 501 not_available_locally stub): /v1/metrics, /v1/scores/aggregations, /v1/traces/export, annotation queues (/v1/annotation-queues/*), and the health endpoints (/health, /v1/health/*).
• Local-only (Cloud returns 501 not_available_on_cloud): /v1/prompts lists the prompt files on disk — the Cloud handler is a documented stub pending an implementation decision.
• Deprecated: /v1/runs/{runId}/traces still works on local for backwards compatibility with older SDK versions, but new code should use /v1/traces?dataset_run_id={runId} — both paths hit the same ClickHouse predicate. The Cloud endpoint has always returned 501.

​

Available endpoints

​

Response format

{
  "error": {
    "code": "string_snake_case",
    "message": "Description of what went wrong"
  }
}

{
  "error": {
    "code": "span_limit_exceeded",
    "message": "Monthly unit limit exceeded. Upgrade your plan for unlimited units.",
    "details": {
      "currentCount": 20000,
      "limit": 20000,
      "upgradeUrl": "https://app.agentmark.co/settings/billing"
    }
  }
}

​

Rate limiting

​

Versioning

​

Why there is no PATCH /v1/traces

• Scores (POST /v1/scores, POST /v1/scores/batch) — attach a graded value (numeric, categorical, or boolean) to a trace or span after the fact. Scores are versioned by created_at and never overwrite the underlying span.
• Comments — free-form human notes on a trace or span, stored alongside the trace as a separate resource.
• Annotation queues (/v1/annotation-queues/*) — structured human-in-the-loop review that produces new score and comment records, again without modifying the trace itself.

​

Filtering on /v1/spans and /v1/scores

• start_date, end_date — ISO 8601 timestamps. Inclusive on both ends.
• user_id, session_id — scope the result to a specific user or session.
• filter — a JSON-encoded filter DSL, identical to the one /v1/traces accepts. Example:
  GET /v1/spans?filter=%7B%22op%22%3A%22and%22%2C%22exprs%22%3A%5B%7B%22field%22%3A%22model%22%2C%22op%22%3A%22eq%22%2C%22value%22%3A%22gpt-4o%22%7D%2C%7B%22field%22%3A%22latency_ms%22%2C%22op%22%3A%22gt%22%2C%22value%22%3A2000%7D%5D%7D
  
  Decoded:
  {
    "op": "and",
    "exprs": [
      { "field": "model", "op": "eq", "value": "gpt-4o" },
      { "field": "latency_ms", "op": "gt", "value": 2000 }
    ]
  }
  
  See Filtering & search for the full operator list.