---
title: "Retrieve usage history"
method: GET
path: "/org/usage/history"
tags: ["Usage"]
---

# Retrieve usage history

`GET /org/usage/history`

## Request

- Base URL: `https://api.context.dev/v1`
- URL: `https://api.context.dev/v1/org/usage/history`
- Auth: HTTP bearer

Retrieve credits and requests over time, bucketed by hour, day, or month. History is kept for one year.

## Query parameters

- `from` string, date-time: Start of the range, as an ISO 8601 timestamp. Defaults to 24 hours before `to` for `hour`, 30 days for `day`, and 366 days for `month`.
- `to` string, date-time: End of the range, as an ISO 8601 timestamp. Defaults to now.
- `interval` 'hour' | 'day' | 'month': Bucket size. `hour` covers up to 7 days; `day` and `month` cover up to 366 days. Buckets start on UTC boundaries.
- `group_by` 'path' | 'key_id' | 'status_code': Split each bucket by endpoint path, API key, or HTTP status code.

## Response `200`

Usage over time

- UsageHistoryResponse
  - `data` UsageHistoryBucket[], required: One bucket per interval, oldest first. Intervals without usage are included with zero totals.
    - `start` string, date-time, required: Start of the bucket, in UTC.
    - `credits_used` integer, required: Credits charged.
    - `request_count` integer, required: Requests made.
    - `groups` object[]: Per-group totals, highest credits first. Present only when `group_by` is set.
      - `value` string, required: The endpoint path, API key ID, or status code this group covers.
      - `credits_used` integer, required: Credits charged.
      - `request_count` integer, required: Requests made.
  - `total_credits_used` integer, required: Credits charged across the range.
  - `total_request_count` integer, required: Requests made across the range.
  - `interval` 'hour' | 'day' | 'month', required: Bucket size used.
  - `from` string, date-time, required: Start of the range.
  - `to` string, date-time, required: End of the range.
  - `key_metadata` KeyMetadata: Credits this request used and your remaining balance.
    - `credits_consumed` integer, required: Credits charged for this request.
    - `credits_remaining` integer, required: Credits remaining for your organization.
  - `request_id` string, uuid, required: Unique ID of this request, also in `X-Request-Id`. Include it when contacting support.

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `429`: Rate limit exceeded (60 requests per minute per organization).
- `500`: Usage data is temporarily unavailable.

## Changes

- **2026-10-21** `61627728926b`: 4 warning
  - added the new `NO_PUBLISHED_MARKDOWN` enum value to the `error_code` response property for the response status `400`
  - added the new `NO_PUBLISHED_MARKDOWN` enum value to the `error_code` response property for the response status `401`
  - added the new `NO_PUBLISHED_MARKDOWN` enum value to the `error_code` response property for the response status `429`
  - added the new `NO_PUBLISHED_MARKDOWN` enum value to the `error_code` response property for the response status `500`
- **2026-10-19** `4ddcf49b9fe5`: 4 info
  - added the optional property `error_data` to the response with the `400` status
  - added the optional property `error_data` to the response with the `401` status
  - added the optional property `error_data` to the response with the `429` status
  - added the optional property `error_data` to the response with the `500` status
- **2026-10-16** `2125f3e94e52`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/context/apis/brand-api/changes/org/usage/history/get.md)

---

[API](https://skmtc.dev/context/apis/brand-api.md) · [All operations](https://skmtc.dev/context/apis/brand-api/llms.txt) · [OpenAPI document](https://skmtc.dev/context/apis/brand-api/revisions/9e2ab7841fb1?raw)