REST API

GET /health POST /v1/traces/async GET /v1/traces GET /v1/traces/:id GET /v1/sessions/:id GET /v1/analytics GET /v1/spans GET /v1/spans/:id GET /v1/sessions/:id/spans

Authentication

Data-plane endpoints under /v1/* require a project API key in the Authorization header. Dashboard endpoints under /dashboard/api/* use authenticated session cookies.

Authorization: Bearer pulse_sk_...

GET `/health`

Health check endpoint for readiness and liveness. Public route with no authentication required.

GET /health

POST `/v1/traces/async`

Queue a batch of traces for asynchronous persistence. This is the primary ingestion path used by the SDK.

Field	Value
Method	`POST`
Body	JSON array of trace objects
Response	`202 Accepted`

curl -X POST https://your-pulse/v1/traces/async \
  -H "Authorization: Bearer pulse_sk_..." \
  -H "Content-Type: application/json" \
  -d '[{
    "trace_id": "uuid",
    "timestamp": "2025-01-01T00:00:00Z",
    "provider": "openai",
    "model_requested": "gpt-4o",
    "request_body": { ... },
    "response_body": { ... },
    "input_tokens": 50,
    "output_tokens": 100,
    "latency_ms": 1200,
    "status": "success"
  }]'

GET `/v1/traces`

Query traces for the authenticated project.

Query parameters

Name	Type	Description
`session_id`	`string`	Filter by session ID.
`provider`	`string`	Filter by provider (`openai`, `anthropic`, `openrouter`).
`model`	`string`	Filter by model name.
`status`	`string`	Filter by status (`success` or `error`).
`date_from`	`string`	Start date (`ISO`, epoch, or `YYYY-MM-DD`).
`date_to`	`string`	End date (`ISO`, epoch, or `YYYY-MM-DD`).
`limit`	`number`	Maximum number of results.
`offset`	`number`	Pagination offset.

GET /v1/traces?provider=openai&status=error&limit=20

Returns { traces: [...], total: number }.

GET `/v1/traces/:id`

Get a single trace by ID.

GET /v1/traces/550e8400-e29b-41d4-a716-446655440000

Returns the trace object or 404.

GET `/v1/spans`

Query agent spans for the authenticated project.

GET /v1/spans?source=claude_code&kind=tool_use&limit=50

GET `/v1/spans/:id`

Get a single span by ID.

GET /v1/spans/550e8400-e29b-41d4-a716-446655440000

GET `/v1/sessions/:id`

Get all traces for a session, ordered by timestamp ascending.

GET /v1/sessions/550e8400-e29b-41d4-a716-446655440000

Returns { sessionId: string, traces: [...] } or 404.

GET `/v1/sessions/:id/spans`

Get all spans for a session, ordered by timestamp ascending.

GET /v1/sessions/550e8400-e29b-41d4-a716-446655440000/spans

Returns { sessionId: string, spans: [...] } or 404.

GET `/v1/analytics`

Aggregated metrics for the authenticated project.

Name	Type	Required	Description
`date_from`	`string`	Yes	Start of date range.
`date_to`	`string`	Yes	End of date range.
`group_by`	`string`	No	Optional grouping dimension.

Dashboard API

Project and API key management for the dashboard lives under /dashboard/api/* and uses session auth cookies.

Trace object

{
  "trace_id": "uuid",
  "timestamp": "ISO 8601",
  "provider": "openai | anthropic | openrouter",
  "model_requested": "gpt-4o",
  "model_used": "gpt-4o-2024-11-20",
  "provider_request_id": "...",
  "request_body": { "...": "..." },
  "response_body": { "...": "..." },
  "input_tokens": 50,
  "output_tokens": 100,
  "output_text": "Hello! How can I...",
  "finish_reason": "stop",
  "status": "success",
  "error": null,
  "cost_cents": 0.18,
  "latency_ms": 1234,
  "session_id": "conv-abc-123",
  "metadata": { "userId": "user-123" }
}