Metrics Endpoints — LumiqTrace API

LumiqTrace exposes four metrics endpoints that power the analytics views in the dashboard. You can call these endpoints directly to build custom reports, integrate metrics into your own internal tooling, or export data to other systems. All four endpoints require a Bearer token and a projectId parameter.

GET /v1/projects/:id/overview

Returns the top-level KPIs for a project along with a timeline, top models by cost, and recent errors. This is the same data shown on the project overview page.

GET https://api.lumiqtrace.com/v1/projects/:id/overview

Authentication: Authorization: Bearer <token>

Path Parameters

string

required

The project ID.

Example Request

curl "https://api.lumiqtrace.com/v1/projects/proj_abc123/overview" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response

{
  "kpis": {
    "totalRequests": 142830,
    "totalCost": 487.34,
    "avgLatency": 921,
    "errorRate": 0.0213
  },
  "timeline": [
    { "hour": "2026-04-20T09:00:00Z", "requests": 1420, "cost": 4.87, "errors": 29 },
    { "hour": "2026-04-20T10:00:00Z", "requests": 1654, "cost": 5.62, "errors": 31 }
  ],
  "topModels": [
    { "model": "gpt-4o", "cost": 312.10, "requests": 89400 },
    { "model": "claude-sonnet-4-6", "cost": 101.44, "requests": 34200 }
  ],
  "recentErrors": [
    {
      "event_id": "550e8400-e29b-41d4-a716-446655440020",
      "model": "gpt-4o",
      "status": "error",
      "error_code": "context_length_exceeded",
      "timestamp": "2026-04-20T10:01:33.000Z"
    }
  ]
}

kpis.totalRequests

number

Total LLM calls in the selected period.

kpis.totalCost

number

Total spend in USD.

kpis.avgLatency

number

Average latency in milliseconds across all calls.

kpis.errorRate

number

Fraction of calls that resulted in an error, timeout, or rate-limited status (0–1).

timeline

object[]

Hourly or daily bucketed metrics series.

topModels

object[]

Top 5 models by total cost descending.

recentErrors

object[]

The 10 most recent non-success events.

GET /v1/costs

Returns a detailed cost breakdown by model, a daily spending trend, month-to-date total, a 30-day linear forecast, and cache utilization rate.

GET https://api.lumiqtrace.com/v1/costs

Authentication: Authorization: Bearer <token>

Query Parameters

projectId

string

required

The project ID.

start

string

ISO 8601 UTC start of the reporting window. Defaults to 30 days ago.

end

string

ISO 8601 UTC end of the reporting window. Defaults to now.

Example Request

curl "https://api.lumiqtrace.com/v1/costs?projectId=proj_abc123&start=2026-04-01T00:00:00Z&end=2026-04-20T23:59:59Z" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response

{
  "byModel": [
    { "model": "gpt-4o", "total_cost": 312.10, "calls": 89400, "avg_cost": 0.00349 },
    { "model": "claude-sonnet-4-6", "total_cost": 101.44, "calls": 34200, "avg_cost": 0.00297 }
  ],
  "dailyTrend": [
    { "date": "2026-04-01", "cost": 22.41 },
    { "date": "2026-04-02", "cost": 24.88 }
  ],
  "mtdTotal": 487.34,
  "forecast30d": 731.01,
  "cacheRate": 0.187
}

byModel

object[]

Per-model cost breakdown sorted by total cost descending.

dailyTrend

object[]

Day-by-day cost series for the requested window.

mtdTotal

number

Month-to-date total spend in USD.

forecast30d

number

Projected 30-day spend in USD based on linear extrapolation of recent daily spending.

cacheRate

number

Fraction of input tokens served from the provider’s prompt cache (0–1).

GET /v1/performance

Returns latency percentiles, average time-to-first-token, tokens-per-second throughput, and timeout rate.

GET https://api.lumiqtrace.com/v1/performance

Authentication: Authorization: Bearer <token>

Query Parameters

projectId

string

required

The project ID.

start

string

ISO 8601 UTC start of the reporting window.

end

string

ISO 8601 UTC end of the reporting window.

Example Request

curl "https://api.lumiqtrace.com/v1/performance?projectId=proj_abc123" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response

{
  "latencyPercentiles": {
    "p50": 712,
    "p90": 1843,
    "p99": 4201
  },
  "avgTtft": 298,
  "tokensPerSec": 48.3,
  "timeoutRate": 0.0041
}

latencyPercentiles.p50

number

Median end-to-end latency in milliseconds.

latencyPercentiles.p90

number

90th percentile latency in milliseconds.

latencyPercentiles.p99

number

99th percentile latency in milliseconds.

avgTtft

number

Average time-to-first-token in milliseconds across streaming calls.

tokensPerSec

number

Average output token generation rate across all calls.

timeoutRate

number

Fraction of calls that timed out (0–1).

GET /v1/errors

Returns error events grouped by error code with counts and trend data, plus a rate limit heatmap for identifying bursty traffic patterns.

GET https://api.lumiqtrace.com/v1/errors

Authentication: Authorization: Bearer <token>

Query Parameters

projectId

string

required

The project ID.

start

string

ISO 8601 UTC start of the reporting window.

end

string

ISO 8601 UTC end of the reporting window.

Example Request

curl "https://api.lumiqtrace.com/v1/errors?projectId=proj_abc123" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response

{
  "errorGroups": [
    {
      "error_code": "context_length_exceeded",
      "count": 412,
      "trend": "increasing",
      "top_model": "gpt-4o"
    },
    {
      "error_code": "rate_limited",
      "count": 87,
      "trend": "stable",
      "top_model": "claude-sonnet-4-6"
    }
  ],
  "rateLimitHeatmap": [
    { "hour": "2026-04-20T14:00:00Z", "rate_limited_count": 34 },
    { "hour": "2026-04-20T15:00:00Z", "rate_limited_count": 12 }
  ]
}

errorGroups

object[]

Error events grouped by error_code, sorted by count descending. Each group includes a trend field ("increasing", "stable", or "decreasing") based on recent trajectory.

rateLimitHeatmap

object[]

Hourly count of rate-limited calls. Use this to identify time windows where your application is hitting provider rate limits.

API Reference

Documentation Index

​GET /v1/projects/:id/overview

​Path Parameters

​Example Request

​Response

​GET /v1/costs

​Query Parameters

​Example Request

​Response

​GET /v1/performance

​Query Parameters

​Example Request

​Response

​GET /v1/errors

​Query Parameters

​Example Request

​Response

GET /v1/projects/:id/overview

Path Parameters

Example Request

Response

GET /v1/costs

Query Parameters

Example Request

Response

GET /v1/performance

Query Parameters

Example Request

Response

GET /v1/errors

Query Parameters

Example Request

Response