API reference

​

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, /v1/filter-schema, and the root /health liveness check.
• Cloud-only (local returns 404 or a 501 not_available_locally stub): /v1/metrics, /v1/scores/aggregations, the structured-search endpoints (/v1/traces/search, /v1/spans/search, /v1/scores/search), annotation queues (/v1/annotation-queues/*), and the dependency health endpoints (/v1/health/*).
• Split: /v1/prompts lists every prompt file on Local. Cloud serves ?name=X lookups only and returns 501 not_available_on_cloud for the full no-name listing.
• 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 resolve to the same query. 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 span limit of 20000 reached. Upgrade your plan to raise this limit.",
    "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. AgentMark versions scores by created_at, and they 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.

​

The filter query grammar

filter      = clause ("and" clause)*
clause      = predicate | "(" predicate ("or" predicate)* ")"
predicate   = field operator [value]

GET /v1/traces?filter=metadata.env%20%3D%20%22prod%22%20and%20status%20%3D%20ERROR

​

Operators

​

Fields

​

Examples

GET /v1/traces?filter=metadata.debug_screenshot_url exists
GET /v1/traces?filter=metadata.debug_screenshot_url = "https://example.com/x"
GET /v1/traces?filter=cost > 0.01 and latency_ms <= 2000
GET /v1/spans?filter=model starts with "gpt-4" and metadata.env = "prod"
GET /v1/traces?filter=(model = "gpt-4o" or model = "o3") and status = ERROR

​

Structured JSON filters (search endpoints)

{
  "filters": [
    { "field": "status", "operator": "equals", "value": "ERROR" },
    { "or": [
      { "field": "model", "operator": "equals", "value": "gpt-4o" },
      { "field": "model", "operator": "equals", "value": "o3" }
    ]},
    { "field": "latency_ms", "operator": "between", "value": [1000, 5000] }
  ],
  "limit": 50,
  "sort_by": "start_time",
  "sort_order": "desc"
}

​

Reading custom metadata

• GET /v1/traces/{traceId}: a trace-level metadata object (the root span’s metadata) and a per-span metadata object on each entry of spans.
• GET /v1/traces/{traceId}/spans/{spanId}: a metadata object alongside the span’s input / output.
• GET /v1/spans and GET /v1/spans/{spanId}: metadata on each span.