Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.lumiqtrace.com/llms.txt

Use this file to discover all available pages before exploring further.

The events endpoint gives you programmatic access to the raw event log for any project. You can filter by model, status, time range, environment, and user ID, making it useful for building custom dashboards, exporting data, or auditing specific LLM calls. Results are cursor-paginated — when there are more records beyond your current page, the response includes a nextCursor value you pass in the next request.

​
Endpoint

GET https://api.lumiqtrace.com/v1/events
Authentication: Authorization: Bearer <token> (see Authentication)

​
Query Parameters

​
projectId
string
required
The ID of the project whose events you want to retrieve.
​
model
string
Filter to events from a specific model. Example: gpt-4o, claude-sonnet-4-6.
​
status
string
Filter by event status. One of success, error, timeout, rate_limited, or cancelled.
​
start
string
ISO 8601 UTC timestamp. Only return events at or after this time. Example: 2026-04-01T00:00:00.000Z.
​
end
string
ISO 8601 UTC timestamp. Only return events before or at this time.
​
environment
string
Filter by deployment environment. Example: production, staging.
​
userId
string
Filter to events attributed to a specific user ID in your application.
​
cursor
string
Pagination cursor from the previous response’s nextCursor field. Omit to start from the beginning.
​
limit
number
Maximum number of events to return. Default 50, maximum 200.

​
Example Request

curl "https://api.lumiqtrace.com/v1/events?projectId=proj_abc123&model=gpt-4o&status=error&start=2026-04-01T00:00:00.000Z&limit=2" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

​
Response

200 OK 
{
  "events": [
    {
      "event_id": "550e8400-e29b-41d4-a716-446655440010",
      "trace_id": "trace-xyz",
      "span_id": "span-010",
      "timestamp": "2026-04-15T14:22:03.000Z",
      "provider": "openai",
      "model": "gpt-4o",
      "operation": "chat",
      "latency_ms": 12043,
      "input_tokens": 8192,
      "output_tokens": 0,
      "cost_usd": 0.0,
      "status": "timeout",
      "error_code": "request_timeout",
      "error_message": "Request timed out after 12000ms",
      "stream": true,
      "environment": "production",
      "user_id": "user_9988",
      "sdk_version": "1.4.2"
    },
    {
      "event_id": "550e8400-e29b-41d4-a716-446655440011",
      "trace_id": "trace-xyz2",
      "span_id": "span-011",
      "timestamp": "2026-04-15T14:19:51.000Z",
      "provider": "openai",
      "model": "gpt-4o",
      "operation": "chat",
      "latency_ms": 1200,
      "input_tokens": 5000,
      "output_tokens": 0,
      "cost_usd": 0.0,
      "status": "error",
      "error_code": "context_length_exceeded",
      "error_message": "This model's maximum context length is 128000 tokens.",
      "stream": false,
      "environment": "production",
      "user_id": "user_1122",
      "sdk_version": "1.4.2"
    }
  ],
  "nextCursor": "eyJsYXN0X2lkIjoiNTUwZTg0MDAtZTI5Yi00MWQ0LWE3MTYtNDQ2NjU1NDQwMDExIn0=",
  "total": 847
}
​
events
LumiqEvent[]
Array of event objects matching your filters. See the Ingest Events page for the full event schema.
​
nextCursor
string | null
Opaque cursor string to pass as the cursor query parameter to retrieve the next page. null when you have reached the last page.
​
total
number
Total number of events matching your filters across all pages.

​
Pagination Example

To page through all results, keep requesting until nextCursor is null:
TypeScript
let cursor: string | null = null;
const allEvents = [];

do {
  const params = new URLSearchParams({ projectId: "proj_abc123", limit: "200" });
  if (cursor) params.set("cursor", cursor);

  const res = await fetch(`https://api.lumiqtrace.com/v1/events?${params}`, {
    headers: { Authorization: "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." },
  });
  const page = await res.json();

  allEvents.push(...page.events);
  cursor = page.nextCursor;
} while (cursor !== null);