GET /api/v1/traces

Query traces for a project with filtering, sorting, and cursor-based pagination.

Request

GET /api/v1/traces?limit=20&name=support-agent&status=ERROR
Authorization: Bearer 2s_live_your_key

Query Parameters

curl Example

# Get the last 20 error traces for a specific agent
curl "https://api.2signal.dev/api/v1/traces?limit=20&status=ERROR&name=support-agent" \
  -H "Authorization: Bearer 2s_live_your_key"

# Paginate through results
curl "https://api.2signal.dev/api/v1/traces?cursor=eyJpZCI6Imxhc3QtdHJhY2UtaWQifQ" \
  -H "Authorization: Bearer 2s_live_your_key"

# Filter by date range and tags
curl "https://api.2signal.dev/api/v1/traces?startDate=2026-03-01T00:00:00Z&endDate=2026-03-15T00:00:00Z&tags=production,v2" \
  -H "Authorization: Bearer 2s_live_your_key"

Response (200)

{
  "data": {
    "traces": [
      {
        "id": "trace-abc-123",
        "name": "support-agent",
        "status": "ERROR",
        "startTime": "2026-03-14T10:00:00.000Z",
        "endTime": "2026-03-14T10:00:02.500Z",
        "durationMs": 2500,
        "totalCost": "0.0034",
        "totalTokens": 1250,
        "tags": ["production", "v2"],
        "metadata": { "version": "2.1", "environment": "prod" },
        "spanCount": 4,
        "scoreCount": 3,
        "createdAt": "2026-03-14T10:00:02.600Z"
      }
    ],
    "nextCursor": "eyJpZCI6InRyYWNlLWFiYy0xMjMifQ"
  },
  "error": null
}

Response Fields

Pagination

The API uses cursor-based pagination. Pass the nextCursor from a response as the cursor parameter in the next request to get the next page.

# Python example: paginate through all traces
import httpx

url = "https://api.2signal.dev/api/v1/traces"
headers = {"Authorization": "Bearer 2s_live_your_key"}
cursor = None

while True:
    params = {"limit": 100}
    if cursor:
        params["cursor"] = cursor

    resp = httpx.get(url, headers=headers, params=params)
    data = resp.json()["data"]

    for trace in data["traces"]:
        print(f"{trace['name']} — {trace['status']} — {trace['durationMs']}ms")

    cursor = data.get("nextCursor")
    if not cursor:
        break

Error Responses