Usage

GET/api/usage

Query your request logs with filtering, pagination, and date range selection. Returns per-request data including model, provider, tokens, cost, latency, and status.

Authentication

This endpoint requires a valid session cookie (from NextAuth). It returns data for the authenticated user only.

Query parameters

Parameter	Type	Default	Description
`from`	ISO 8601 string	30 days ago	Start of date range (inclusive)
`to`	ISO 8601 string	Now	End of date range (inclusive)
`model`	string	All	Filter by model name (e.g., `gpt-4o`)
`limit`	integer	50	Number of records per page (max 200)
`page`	integer	1	Page number for pagination

Response

200 OK

{
  "data": [
    {
      "id": "clx1abc123",
      "model": "gpt-4o",
      "provider": "openai",
      "endpoint": "/api/v1/chat/completions",
      "tokensIn": 24,
      "tokensOut": 128,
      "costUsd": 0.00456,
      "latencyMs": 1243,
      "statusCode": 200,
      "experimentId": null,
      "experimentArm": null,
      "createdAt": "2026-03-06T12:00:00.000Z"
    },
    {
      "id": "clx1def456",
      "model": "claude-sonnet-4-20250514",
      "provider": "anthropic",
      "endpoint": "/api/v1/chat/completions",
      "tokensIn": 18,
      "tokensOut": 95,
      "costUsd": 0.00339,
      "latencyMs": 987,
      "statusCode": 200,
      "experimentId": "clx1exp789",
      "experimentArm": "B",
      "createdAt": "2026-03-06T11:55:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1247,
    "totalPages": 25
  }
}

Record fields

Field	Type	Description
`id`	string	Unique request identifier
`model`	string	Model used for the request
`provider`	string	`openai`, `anthropic`, or `google`
`endpoint`	string	Proxy endpoint that was called
`tokensIn`	integer \| null	Input token count (null for non-text endpoints)
`tokensOut`	integer \| null	Output token count
`costUsd`	number \| null	Estimated cost in USD
`latencyMs`	integer	End-to-end request latency in milliseconds
`statusCode`	integer	HTTP status code returned to the caller
`experimentId`	string \| null	Experiment ID if routed through an experiment
`experimentArm`	string \| null	`A` or `B` if part of an experiment
`createdAt`	ISO 8601	Timestamp of the request

Examples

Fetch last 30 days of usage

curl

curl "https://your-meridian.vercel.app/api/usage" \
  -H "Cookie: next-auth.session-token=YOUR_SESSION"

Filter by model and date range

curl

curl "https://your-meridian.vercel.app/api/usage?model=gpt-4o&from=2026-03-01T00:00:00Z&to=2026-03-06T23:59:59Z&limit=100" \
  -H "Cookie: next-auth.session-token=YOUR_SESSION"

Paginate through results

JavaScript

async function fetchAllUsage(sessionToken) {
  let page = 1;
  let allRecords = [];

  while (true) {
    const res = await fetch(
      `https://your-meridian.vercel.app/api/usage?page=${page}&limit=200`,
      { headers: { Cookie: `next-auth.session-token=${sessionToken}` } }
    );
    const { data, pagination } = await res.json();
    allRecords.push(...data);

    if (page >= pagination.totalPages) break;
    page++;
  }

  return allRecords;
}