Get AI credit usage by AI feature and time period

Returns recorded AI usage for an organization. Calendar buckets use UTC; weeks start on Monday. Requires organization administrator permissions.

Available in MCP

get

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

A unique entity identifier

Pattern: ^[a-zA-Z0-9_-]+$

Query parameters

fromstring · date-timeRequired

Inclusive start timestamp. Cannot be older than two years from now.

tostring · date-timeRequired

Exclusive end timestamp.

intervalstring · enumOptional

UTC calendar interval for AI usage, with weeks starting on Monday.

Default: dayPossible values:

Responses

200

AI usage, including empty periods in the requested range.

application/json

fromstring · date-timeRequired

Inclusive start of the queried range.

tostring · date-timeRequired

Exclusive end of the queried range, capped at the current instant.

get/orgs/{organizationId}/billing/ai-usage

GET /v1/orgs/{organizationId}/billing/ai-usage?from=2026-01-01T00%3A00%3A00.000Z&to=2026-01-01T00%3A00%3A00.000Z HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

AI usage, including empty periods in the requested range.

{
  "from": "2026-01-01T00:00:00.000Z",
  "to": "2026-01-01T00:00:00.000Z",
  "periods": [
    {
      "date": "2026-01-01",
      "credits": 1,
      "features": [
        {
          "feature": "text",
          "credits": 1,
          "creditsPercent": 1
        }
      ]
    }
  ]
}