Read API

The read API hands your data back. Every run, event, evaluation result, and agent on your account is reachable with a read-scoped key, with cursor pagination and no per-call charge.

It is served by the control plane, not the ingest tier:

https://agentping.io/v1/...

Authentication and scope

Read endpoints require an API key with the read scope. Mint one in Settings, API keys and grant it read; the ingest scope and the read scope are separate, so a key your SDK uses to send data does not automatically read it back, and vice versa. Keys created before scopes existed keep working for ingest only.

curl https://agentping.io/v1/runs \
  -H "Authorization: Bearer apk_eu_018f3a2b9c1d7e8fa4b9c2d7e8f1a3b6"

A key without the read scope returns 403 insufficient_scope.

Rate limit

Read requests are limited to 60 per minute per key. Over the limit returns 429 with a Retry-After header in seconds. This is generous for backfills and automations; for a full account dump prefer a bulk export.

Retention

Reads are bounded by your plan's run-history horizon. A from/to window that reaches past it is silently clamped, never an error: list responses carry a retention_horizon field with the oldest timestamp you can read, and a window entirely before it returns an empty data array. See data retention.

Pagination

List endpoints use opaque cursor pagination. Pass per_page (max 100, default 50) and follow next_cursor until it is null:

{
  "data": [ ... ],
  "next_cursor": "eyJpZCI6...",
  "retention_horizon": "2026-03-15T00:00:00+00:00"
}

curl "https://agentping.io/v1/runs?per_page=100&cursor=eyJpZCI6..." \
  -H "Authorization: Bearer apk_eu_..."

GET /v1/runs

List runs newest-first.

Each item is a run summary:

{
  "id": "run_eu_018f3a2b9c1d7e8fa4b9c2d7e8f1a3b6",
  "agent": "support-triage",
  "status": "success",
  "goal": "Route the ticket to the right department",
  "customer_id": "acme-corp",
  "feature": "ticket-routing",
  "started_at": "2026-05-15T14:32:01+00:00",
  "finished_at": "2026-05-15T14:32:05+00:00",
  "duration_ms": 4666,
  "cost_usd": 0.0142,
  "total_input_tokens": 1200,
  "total_output_tokens": 340,
  "step_count": 3,
  "error_count": 0
}

GET /v1/runs/{id}

One run, in full. Returns the same summary plus metadata, tools, and output. A run id from another team returns 404 (not 403), so a caller can't probe which ids exist.

GET /v1/runs/{id}/events

The run's events in timestamp order (up to 1000). When an event has an offloaded payload, data is the slimmed inline copy and payload_url points at the full body:

{
  "data": [
    {
      "id": "evt_eu_018f3a2b9c1d7e8fa4b9c2d7e8f1a3b7",
      "type": "llm_call",
      "ts": "2026-05-15T14:32:02.456Z",
      "data": { "provider": "anthropic", "model": "claude-opus-4-7" },
      "payload_url": "https://agentping.io/v1/runs/run_eu_.../events/evt_eu_.../payload"
    }
  ]
}

GET /v1/runs/{id}/events/{eventId}/payload

The full event payload, fetched from the payload store when one exists, otherwise the inline copy. Payloads are only available within your plan's step-detail horizon.

GET /v1/runs/{id}/evaluation

The run's evaluation in the public shape, with internal stages collapsed to a single evaluation type:

{
  "data": {
    "type": "evaluation",
    "status": "complete",
    "result": "goal_achieved",
    "quality": 4,
    "issues": [],
    "reasoning": "The ticket was routed to billing, matching the goal.",
    "evaluated_at": "2026-05-15T15:02:11+00:00"
  }
}

status is one of complete, pending, covered_by_routine_baseline, or returned_to_allowance. quality is 0 to 5 when present. A run that was never evaluated returns 404.

GET /v1/agents

Every agent on the team with rolled-up health:

{
  "data": [
    {
      "id": "agt_eu_018f3a2b9c1d7e8fa4b9c2d7e8f1a3b9",
      "slug": "support-triage",
      "first_seen_at": "2026-02-01T09:14:00+00:00",
      "last_seen_at": "2026-05-15T14:32:01.156Z",
      "health_pass_rate_24h": 0.9821,
      "quality_7d": 88
    }
  ]
}

last_seen_at is the most recent run received for the agent; health_pass_rate_24h and quality_7d are null until there is data.