API Reference

The Spanloom REST API lets you query traces, manage projects, and configure alerts from your own tooling.

Base URL and authentication

All API requests go to:

https://api.spanloom.com/v1

Authenticate every request with your API key in the Authorization header:

Authorization: Bearer spl_your_key_here

API keys are scoped per project. Generate one from Project Settings in the Spanloom dashboard.

Traces

Traces represent a single request through your LLM application, composed of one or more spans.

List traces

GET /traces

Parameter	Type	Description
`project_id`	string	Required. Filter traces by project.
`from`	ISO 8601	Start of time range. Defaults to 24 hours ago.
`to`	ISO 8601	End of time range. Defaults to now.
`limit`	integer	Number of results. Max 500. Default 100.
`cursor`	string	Pagination cursor from previous response.

Get a trace

GET /traces/{trace_id}

Returns a single trace with all child spans, attributes, and computed cost.

Example response

{
  "id": "tr_01HX...",
  "project_id": "proj_abc123",
  "started_at": "2026-06-10T14:22:01.423Z",
  "duration_ms": 1840,
  "spans": [
    {
      "id": "sp_01HX...",
      "name": "llm_answer",
      "model": "gpt-4o",
      "input_tokens": 1204,
      "output_tokens": 312,
      "cost_usd": 0.00912,
      "duration_ms": 1612
    }
  ],
  "total_cost_usd": 0.00912
}

Spans

Spans are the individual steps within a trace: LLM calls, retrieval operations, tool invocations.

List spans for a trace

GET /traces/{trace_id}/spans

Returns all spans belonging to the given trace, ordered by start time.

Projects

List projects

GET /projects

Returns all projects in your workspace. No parameters required.

Create a project

POST /projects

Field	Type	Description
`name`	string	Required. Display name for the project.
`description`	string	Optional. Shown in the dashboard.
`retention_days`	integer	How long to retain trace data. Default 30. Max 365.

Alerts

Configure threshold-based alerts for latency, error rate, cost, and prompt drift.

List alerts

GET /projects/{project_id}/alerts

Create an alert

POST /projects/{project_id}/alerts

{
  "name": "High cost spike",
  "metric": "cost_usd_hourly",
  "threshold": 5.0,
  "condition": "gt",
  "webhook_url": "https://your-endpoint.example.com/hooks/spanloom"
}

Rate limits

The API is rate-limited to 1000 requests per minute per API key. Responses include the following headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests per minute.
`X-RateLimit-Remaining`	Requests remaining in current window.
`X-RateLimit-Reset`	Unix timestamp when the window resets.

A 429 Too Many Requests response includes a Retry-After header with the number of seconds to wait.