Guide

Pagination

Atlas preview endpoints use simple cursor-free pagination via limit and optional after_id parameters. High-volume consumers should prefer webhook delivery over polling these endpoints.

List sessions

Returns a flat array of session objects ordered by created_at descending. Pass the last seen id as after_id to advance the cursor.

GET /v1/atlas/sessions?limit=20&after_id=sess_01HX5Z
Response: {
  "data": [ /* array of session objects */ ],
  "next_cursor": "sess_01HX6B",
  "has_more": true
}

List conversation events

Returns a chronologically ordered array of inbound and outbound events for a given conversation. Use limit to batch fetch; avoid unbounded iteration in high-throughput channels.

GET /v1/atlas/conversations/{id}/events?limit=50
Response: {
  "data": [ /* event objects */ ],
  "has_more": false
}

List knowledge sources

Returns the org-owned knowledge corpus with source type, ingestion status, and citation metadata. Archived or deleted sources are excluded by default.

GET /v1/atlas/knowledge?limit=10&status=active
Response: {
  "data": [
    {
      "id": "kn_01HX9Z",
      "source_type": "url",
      "url": "https://acme.com/pricing",
      "title": "Pricing Page",
      "ingested_at": "2026-05-01T12:00:00Z"
    }
  ],
  "has_more": true
}

List runs for a session

Returns ReAct loop iteration records for a session, including intent detected, tools called, and outcome status. Runs are immutable once recorded.

GET /v1/atlas/sessions/{id}/runs?limit=10
Response: {
  "data": [
    {
      "id": "run_01HXAB",
      "iteration": 1,
      "intent": "booking_request",
      "status": "completed",
      "tools_called": ["retrieve_knowledge", "create_booking"],
      "created_at": "2026-05-21T10:01:00Z"
    }
  ],
  "has_more": false
}

Pagination guidelines

  • Use limit values of 20-50 for interactive use; higher limits are available for batch export but increase response payload size.
  • Always check has_more before issuing a follow-up request to avoid unnecessary API calls.
  • For webhook-integrated architectures, prefer event push over polling pagination entirely.
  • Cursor tokens are opaque strings; do not parse or construct them manually.
  • Pagination state should be scoped to the requesting principal and org; cross-org pagination is not permitted.