Book a demo

get_api_usage

Get API usage

read collection tenant-private since 2026-10-01

Counts the requests the org's API keys made, per key per UTC day, newest day first: how many were served and how many were refused for passing a key's limits. Live and test keys are kept apart: each row names its mode, and mode narrows to one. One key with key_id, or all of them. The window is since to until, both UTC days and both included: the last 30 days by default, at most 92. BK_ keys are not metered and have no usage.

Contract

shape
collection
authority
read
evidence
none
subscription
false
permission
any one of: org.admin (carried by the caller's role template in the org `org_id`); api_key.read (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first
idempotency
safe
emits
none
MCP tool
get_api_usage
REST
POST https://api.containertradehq.com/v1/cap/get_api_usage

Idempotency: a read: calling again changes nothing

Inputs

nametyperequiredvalidation
org_idorg_idrequiredtradehq-org-id; 1 to 20 characters
The org whose keys they are.
key_idtextoptional1 to 12 characters
One key's usage. Absent, every key's.
sincedateoptionaldate, YYYY-MM-DD
The first UTC day, included. Defaults to 29 days before until.
untildateoptionaldate, YYYY-MM-DD
The last UTC day, included. Defaults to today.
modeone_ofoptionalone of live, test
live or test: only the keys of that mode. Absent, both, each row naming its mode.

Paginated: next next_after · ceiling not_declared

Response

  • items · object[]
  • next_after · stringnull · Pass as `after` for the next page; null on the last one.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "day": {
            "type": "string",
            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
            "format": "date",
            "description": "The UTC day.",
            "x-data-class": "operational"
          },
          "key_id": {
            "type": "string",
            "description": "The key.",
            "x-data-class": "operational"
          },
          "mode": {
            "type": "string",
            "enum": [
              "live",
              "test"
            ],
            "description": "The key's mode.",
            "x-data-class": "operational"
          },
          "requests": {
            "type": "integer",
            "description": "Requests served that day.",
            "x-data-class": "operational"
          },
          "refused": {
            "type": "integer",
            "description": "Requests refused that day for passing a limit.",
            "x-data-class": "operational"
          }
        },
        "required": [
          "day",
          "key_id",
          "mode",
          "requests",
          "refused"
        ],
        "additionalProperties": false
      }
    },
    "next_after": {
      "type": [
        "string",
        "null"
      ],
      "description": "Pass as `after` for the next page; null on the last one."
    }
  },
  "required": [
    "items",
    "next_after"
  ],
  "additionalProperties": false
}

Refusals

not yet declared

The platform refusals apply to every call: version, authentication, authority, validation and rate limits, each in the same envelope.

Surfaces

DesktopF
MobileF
APIF
MCPF
VoiceD4
PushN
OneBoxN
OutboundN
  • Voice: degraded: visualization
  • Push: emits nothing
  • OneBox: no document originates API usage
  • Outbound: crosses to no counterparty

Events

None emitted.

Related

create_api_key, create_service_account, get_view_default, list_capability_events, list_saved_views, revoke_api_key, rotate_api_key, save_view, set_api_key_limits, set_api_key_version, set_my_view_default, set_org_view_default