Skip to main content

Usage

Preview

Token usage, the activity log and the self-service spend cap. Reference for API version next.

On this page
PreviewDownload OpenAPI (JSON)Versioning

Get your usage

GET /api/v1/usage/me

Token, request and GBP totals for the caller over a window, optionally by day. Requires the usage:read member scope.

Authentication

  • API key in X-API-Key
  • API key or session token in Authorization: Bearer

Query parameters

  • since string

    ISO-8601 start of the window (inclusive). A date without a time zone is read as UTC.

    Examples
    2026-11-01
  • until string

    ISO-8601 end of the window (exclusive).

    Examples
    2026-11-11
  • group_by_day boolean
    Default
    true

Responses

  • 200 The usage summary.

    application/json

    Body (application/json)

    • scope string
      One of
      user org
    • scope_id string or null
    • since string or null
    • until string or null
    • totals object
      8 fields in totals
      • input_tokens integer
      • output_tokens integer
      • total_tokens integer
      • price_gbp number

        Customer charge for the window, in GBP.

      • requests integer
      • p50_latency_ms number or null
      • p95_latency_ms number or null
      • cache_hit_rate_pct number or null
    • daily array of objects
      6 fields in daily
      • date string

        YYYY-MM-DD (UTC).

      • input_tokens integer
      • output_tokens integer
      • total_tokens integer
      • price_gbp number
      • requests integer
    • rates object
  • 400 The request was malformed or failed a server-side check.Error envelope
  • 401 Missing, invalid, expired or revoked credentials.Error envelope
  • 403 The credential is valid but lacks a required scope or permission.Error envelope
  • 429 A per-user limit was exceeded (the Platform API, embeddings or rerank). This response does not use the error envelope. Wait for Retry-After seconds.

    application/json

    Headers

    • X-Request-ID string

      The request's correlation id (yours, or one BreachLine generated). Quote it to support.

    • Retry-After integer

      Seconds to wait before retrying.

    Body (application/json)

    • detail string Required
    • retry_after integer Required
      Always
      60

Example

cURL
curl "https://api.breachline.io/api/v1/usage/me" \
  -H "Authorization: Bearer $BREACHLINE_API_KEY"
Example 200 response
{
  "scope": "user",
  "scope_id": "string",
  "since": "string",
  "until": "string",
  "totals": {
    "input_tokens": 0,
    "output_tokens": 0,
    "total_tokens": 0,
    "price_gbp": 0,
    "requests": 0,
    "p50_latency_ms": 0,
    "p95_latency_ms": 0,
    "cache_hit_rate_pct": 0
  },
  "daily": [
    {
      "date": "string",
      "input_tokens": 0,
      "output_tokens": 0,
      "total_tokens": 0,
      "price_gbp": 0,
      "requests": 0
    }
  ],
  "rates": {}
}

List your recent requests

GET /api/v1/usage/me/logs

The per-request activity log. Metadata only; prompts and responses are never stored in it.

Authentication

  • API key in X-API-Key
  • API key or session token in Authorization: Bearer

Query parameters

  • limit integer
    Default
    20
    Minimum
    1
    Maximum
    100
  • offset integer
    Default
    0
    Minimum
    0

Responses

  • 200 Log entries, newest first.

    application/json

    Body (application/json)

    • limit integer
    • offset integer
    • has_more boolean
    • logs array of objects
      11 fields in logs
      • id string
      • created_at string (date-time)
      • endpoint string
        Examples
        /api/v1/llm/v1/chat/completions
      • tier string

        The public Nebula model label.

      • input_tokens integer
      • output_tokens integer
      • total_tokens integer
      • response_status integer or null
      • cache_read_tokens integer
      • cache_write_tokens integer
      • latency_ms integer or null
  • 401 Missing, invalid, expired or revoked credentials.Error envelope
  • 403 The credential is valid but lacks a required scope or permission.Error envelope
  • 429 A per-user limit was exceeded (the Platform API, embeddings or rerank). This response does not use the error envelope. Wait for Retry-After seconds.

    application/json

    Headers

    • X-Request-ID string

      The request's correlation id (yours, or one BreachLine generated). Quote it to support.

    • Retry-After integer

      Seconds to wait before retrying.

    Body (application/json)

    • detail string Required
    • retry_after integer Required
      Always
      60

Example

cURL
curl "https://api.breachline.io/api/v1/usage/me/logs" \
  -H "Authorization: Bearer $BREACHLINE_API_KEY"
Example 200 response
{
  "limit": 0,
  "offset": 0,
  "has_more": true,
  "logs": [
    {
      "id": "string",
      "created_at": "2026-11-11T00:00:00Z",
      "endpoint": "/api/v1/llm/v1/chat/completions",
      "tier": "string",
      "input_tokens": 0,
      "output_tokens": 0,
      "total_tokens": 0,
      "response_status": 0,
      "cache_read_tokens": 0,
      "cache_write_tokens": 0,
      "latency_ms": 0
    }
  ]
}

Get your budget burn

GET /api/v1/usage/me/budget

Token burn for the current day or month window, plus an error-rate breakdown.

Authentication

  • API key in X-API-Key
  • API key or session token in Authorization: Bearer

Query parameters

  • window string

    Budget window.

    One of
    day month
    Default
    day
  • since string

    ISO-8601 start of the window (inclusive). A date without a time zone is read as UTC.

    Examples
    2026-11-01
  • until string

    ISO-8601 end of the window (exclusive).

    Examples
    2026-11-11

Responses

  • 200 Budget view.

    application/json

    Body (application/json)

    • budget object
      5 fields in budget
      • scope string
      • scope_id string or null
      • window string
        One of
        day month
      • window_start string (date-time)
      • window_end string (date-time)
    • error_rate_by_model array of objects
  • 401 Missing, invalid, expired or revoked credentials.Error envelope
  • 403 The credential is valid but lacks a required scope or permission.Error envelope
  • 429 A per-user limit was exceeded (the Platform API, embeddings or rerank). This response does not use the error envelope. Wait for Retry-After seconds.

    application/json

    Headers

    • X-Request-ID string

      The request's correlation id (yours, or one BreachLine generated). Quote it to support.

    • Retry-After integer

      Seconds to wait before retrying.

    Body (application/json)

    • detail string Required
    • retry_after integer Required
      Always
      60

Example

cURL
curl "https://api.breachline.io/api/v1/usage/me/budget" \
  -H "Authorization: Bearer $BREACHLINE_API_KEY"
Example 200 response
{
  "budget": {
    "scope": "string",
    "scope_id": "string",
    "window": "day",
    "window_start": "2026-11-11T00:00:00Z",
    "window_end": "2026-11-11T00:00:00Z"
  },
  "error_rate_by_model": [
    {}
  ]
}

Get your spend cap

GET /api/v1/usage/me/budget/cap

Authentication

  • API key in X-API-Key
  • API key or session token in Authorization: Bearer

Responses

  • 200 The cap, or nulls when none is set.

    application/json

    Body (application/json)

    • cap_gbp number or null
    • window string or null
      One of
      day month null
  • 401 Missing, invalid, expired or revoked credentials.Error envelope
  • 403 The credential is valid but lacks a required scope or permission.Error envelope
  • 429 A per-user limit was exceeded (the Platform API, embeddings or rerank). This response does not use the error envelope. Wait for Retry-After seconds.

    application/json

    Headers

    • X-Request-ID string

      The request's correlation id (yours, or one BreachLine generated). Quote it to support.

    • Retry-After integer

      Seconds to wait before retrying.

    Body (application/json)

    • detail string Required
    • retry_after integer Required
      Always
      60

Example

cURL
curl "https://api.breachline.io/api/v1/usage/me/budget/cap" \
  -H "Authorization: Bearer $BREACHLINE_API_KEY"
Example 200 response
{
  "cap_gbp": 0,
  "window": "day"
}

Set your spend cap

PUT /api/v1/usage/me/budget/cap

A self-service ceiling on retail GBP spend per day or month. Once the window's spend reaches it, LLM requests get 402 until the window resets or the cap is raised. Requires the settings:write member scope.

Authentication

  • API key in X-API-Key
  • API key or session token in Authorization: Bearer

Query parameters

  • max_gbp number Required
    Greater than
    0
  • window string

    Budget window.

    One of
    day month
    Default
    day

Responses

  • 200 Saved.

    application/json

    Body (application/json)

    • ok boolean
    • cap_gbp number
    • window string
      One of
      day month
  • 401 Missing, invalid, expired or revoked credentials.Error envelope
  • 403 The credential is valid but lacks a required scope or permission.Error envelope
  • 422 The request body or parameters failed schema validation.Error envelope
  • 429 A per-user limit was exceeded (the Platform API, embeddings or rerank). This response does not use the error envelope. Wait for Retry-After seconds.

    application/json

    Headers

    • X-Request-ID string

      The request's correlation id (yours, or one BreachLine generated). Quote it to support.

    • Retry-After integer

      Seconds to wait before retrying.

    Body (application/json)

    • detail string Required
    • retry_after integer Required
      Always
      60

Example

cURL
curl -X PUT "https://api.breachline.io/api/v1/usage/me/budget/cap?max_gbp=0" \
  -H "Authorization: Bearer $BREACHLINE_API_KEY"
Example 200 response
{
  "ok": true,
  "cap_gbp": 0,
  "window": "day"
}

Remove your spend cap

DELETE /api/v1/usage/me/budget/cap

Requires the settings:write member scope.

Authentication

  • API key in X-API-Key
  • API key or session token in Authorization: Bearer

Responses

  • 200 Removed.
  • 401 Missing, invalid, expired or revoked credentials.Error envelope
  • 403 The credential is valid but lacks a required scope or permission.Error envelope
  • 429 A per-user limit was exceeded (the Platform API, embeddings or rerank). This response does not use the error envelope. Wait for Retry-After seconds.

    application/json

    Headers

    • X-Request-ID string

      The request's correlation id (yours, or one BreachLine generated). Quote it to support.

    • Retry-After integer

      Seconds to wait before retrying.

    Body (application/json)

    • detail string Required
    • retry_after integer Required
      Always
      60

Example

cURL
curl -X DELETE "https://api.breachline.io/api/v1/usage/me/budget/cap" \
  -H "Authorization: Bearer $BREACHLINE_API_KEY"

Get organization usage

GET /api/v1/usage/org/{org_id}

Usage for an organization you are a member of.

Authentication

  • API key in X-API-Key
  • API key or session token in Authorization: Bearer

Path parameters

  • org_id string Required

    Organization id.

Query parameters

  • since string

    ISO-8601 start of the window (inclusive). A date without a time zone is read as UTC.

    Examples
    2026-11-01
  • until string

    ISO-8601 end of the window (exclusive).

    Examples
    2026-11-11
  • group_by_day boolean
    Default
    true

Responses

  • 200 The usage summary.

    application/json

    Body (application/json)

    • scope string
      One of
      user org
    • scope_id string or null
    • since string or null
    • until string or null
    • totals object
      8 fields in totals
      • input_tokens integer
      • output_tokens integer
      • total_tokens integer
      • price_gbp number

        Customer charge for the window, in GBP.

      • requests integer
      • p50_latency_ms number or null
      • p95_latency_ms number or null
      • cache_hit_rate_pct number or null
    • daily array of objects
      6 fields in daily
      • date string

        YYYY-MM-DD (UTC).

      • input_tokens integer
      • output_tokens integer
      • total_tokens integer
      • price_gbp number
      • requests integer
    • rates object
  • 401 Missing, invalid, expired or revoked credentials.Error envelope
  • 403 The credential is valid but lacks a required scope or permission.Error envelope
  • 429 A per-user limit was exceeded (the Platform API, embeddings or rerank). This response does not use the error envelope. Wait for Retry-After seconds.

    application/json

    Headers

    • X-Request-ID string

      The request's correlation id (yours, or one BreachLine generated). Quote it to support.

    • Retry-After integer

      Seconds to wait before retrying.

    Body (application/json)

    • detail string Required
    • retry_after integer Required
      Always
      60

Example

cURL
curl "https://api.breachline.io/api/v1/usage/org/{org_id}" \
  -H "Authorization: Bearer $BREACHLINE_API_KEY"
Example 200 response
{
  "scope": "user",
  "scope_id": "string",
  "since": "string",
  "until": "string",
  "totals": {
    "input_tokens": 0,
    "output_tokens": 0,
    "total_tokens": 0,
    "price_gbp": 0,
    "requests": 0,
    "p50_latency_ms": 0,
    "p95_latency_ms": 0,
    "cache_hit_rate_pct": 0
  },
  "daily": [
    {
      "date": "string",
      "input_tokens": 0,
      "output_tokens": 0,
      "total_tokens": 0,
      "price_gbp": 0,
      "requests": 0
    }
  ],
  "rates": {}
}

List organization requests

GET /api/v1/usage/org/{org_id}/logs

Authentication

  • API key in X-API-Key
  • API key or session token in Authorization: Bearer

Path parameters

  • org_id string Required

    Organization id.

Query parameters

  • limit integer
    Default
    20
    Minimum
    1
    Maximum
    100
  • offset integer
    Default
    0
    Minimum
    0

Responses

  • 200 Log entries, newest first.

    application/json

    Body (application/json)

    • limit integer
    • offset integer
    • has_more boolean
    • logs array of objects
      11 fields in logs
      • id string
      • created_at string (date-time)
      • endpoint string
        Examples
        /api/v1/llm/v1/chat/completions
      • tier string

        The public Nebula model label.

      • input_tokens integer
      • output_tokens integer
      • total_tokens integer
      • response_status integer or null
      • cache_read_tokens integer
      • cache_write_tokens integer
      • latency_ms integer or null
  • 401 Missing, invalid, expired or revoked credentials.Error envelope
  • 403 The credential is valid but lacks a required scope or permission.Error envelope
  • 429 A per-user limit was exceeded (the Platform API, embeddings or rerank). This response does not use the error envelope. Wait for Retry-After seconds.

    application/json

    Headers

    • X-Request-ID string

      The request's correlation id (yours, or one BreachLine generated). Quote it to support.

    • Retry-After integer

      Seconds to wait before retrying.

    Body (application/json)

    • detail string Required
    • retry_after integer Required
      Always
      60

Example

cURL
curl "https://api.breachline.io/api/v1/usage/org/{org_id}/logs" \
  -H "Authorization: Bearer $BREACHLINE_API_KEY"
Example 200 response
{
  "limit": 0,
  "offset": 0,
  "has_more": true,
  "logs": [
    {
      "id": "string",
      "created_at": "2026-11-11T00:00:00Z",
      "endpoint": "/api/v1/llm/v1/chat/completions",
      "tier": "string",
      "input_tokens": 0,
      "output_tokens": 0,
      "total_tokens": 0,
      "response_status": 0,
      "cache_read_tokens": 0,
      "cache_write_tokens": 0,
      "latency_ms": 0
    }
  ]
}

Get organization budget burn

GET /api/v1/usage/org/{org_id}/budget

Authentication

  • API key in X-API-Key
  • API key or session token in Authorization: Bearer

Path parameters

  • org_id string Required

    Organization id.

Query parameters

  • window string

    Budget window.

    One of
    day month
    Default
    day
  • since string

    ISO-8601 start of the window (inclusive). A date without a time zone is read as UTC.

    Examples
    2026-11-01
  • until string

    ISO-8601 end of the window (exclusive).

    Examples
    2026-11-11

Responses

  • 200 Budget view.

    application/json

    Body (application/json)

    • budget object
      5 fields in budget
      • scope string
      • scope_id string or null
      • window string
        One of
        day month
      • window_start string (date-time)
      • window_end string (date-time)
    • error_rate_by_model array of objects
  • 401 Missing, invalid, expired or revoked credentials.Error envelope
  • 403 The credential is valid but lacks a required scope or permission.Error envelope
  • 429 A per-user limit was exceeded (the Platform API, embeddings or rerank). This response does not use the error envelope. Wait for Retry-After seconds.

    application/json

    Headers

    • X-Request-ID string

      The request's correlation id (yours, or one BreachLine generated). Quote it to support.

    • Retry-After integer

      Seconds to wait before retrying.

    Body (application/json)

    • detail string Required
    • retry_after integer Required
      Always
      60

Example

cURL
curl "https://api.breachline.io/api/v1/usage/org/{org_id}/budget" \
  -H "Authorization: Bearer $BREACHLINE_API_KEY"
Example 200 response
{
  "budget": {
    "scope": "string",
    "scope_id": "string",
    "window": "day",
    "window_start": "2026-11-11T00:00:00Z",
    "window_end": "2026-11-11T00:00:00Z"
  },
  "error_rate_by_model": [
    {}
  ]
}

Search documentation

Type to search guides, the API reference, the CLI and the console guide.

    Enter open↑ ↓ moveEsc close