---
title: "Get your API usage"
method: GET
path: "/v1/me/usage"
tags: ["Account"]
---

# Get your API usage

`GET /v1/me/usage`

## Request

- Base URL: `https://api.gunspec.io`
- URL: `https://api.gunspec.io/v1/me/usage`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Returns request counts for your key against your plan allowance, what is left of today's daily limit and when it resets, and how many requests came through the hosted MCP server against its lower daily limit. Defaults to the current billing month; pass `days` for a trailing window instead.

You do not need this call to pace yourself: every `/v1` response already carries `X-Daily-Limit`, `X-Daily-Remaining` and `X-Daily-Reset` for the key that made it, and this call is itself a request that counts. Use it to reconcile, and to see every key at once. `daily` is the limit that is enforced, counted per key; `currentMonth` is a running total for the billing period.

Requires an API key belonging to a user account. Acts on the calling account's own data.

## Query parameters

- `month` string
- `days` integer

## Response `200`

Get your API usage

- object
  - `success` boolean, required: Always true on a successful response. Every error carries `false` and an `error` object instead.
  - `data` object, required: The response payload.
    - `currentMonth` object: Totals for the reported period, meaning the current billing month, or the trailing window when `days` is given.
      - `used` integer: Requests served in the reported period across every key on the account. Calls a limit refused with a 429 are not counted: they spent nothing, and this is the figure the monthly allowance is enforced against.
      - `limit` integer: Requests your plan allows in the period. Enforced: once `used` reaches it every call is refused with `MONTHLY_CAP_EXCEEDED` until `resetsAt`.
      - `remaining` integer: Requests left in the period, never below zero.
      - `percentage` number: Share of records, 0 to 100.
      - `resetsAt` string: When the monthly counter returns to zero: midnight UTC on the first of the next month, for every plan. The same instant as `X-Monthly-Reset`.
    - `daily` object: What is left of today, against the limit that is enforced. Each key is counted and limited on its own.
      - `limitPerKey` integer, nullable: Requests one key may make per UTC day on this plan. The limit applies to each key separately, which is why there is no account total to compare it with. Null when the plan has no daily ceiling.
      - `usedToday` integer: Requests made today (UTC) across every key on the account. Not comparable with `limitPerKey` unless the account has one key: each key is held to the limit on its own.
      - `busiestKeyToday` object, nullable: The key nearest its daily limit, or null when no key has made a request today.
        - `keyId` string: Id of the key closest to its daily limit today.
        - `keyName` string: The label you gave the key.
        - `used` integer: Requests that key made today. It counts calls the limit refused too, so it can exceed `limitPerKey`: a figure well past the limit means that key kept calling after being told to stop.
        - `remaining` integer, nullable: Requests that key has left today, never below zero. Null when the plan has no daily ceiling.
        - `percentage` integer: Share of `limitPerKey` that key has used, rounded. It can exceed 100.
      - `resetsAt` string: When every daily counter returns to zero: the next midnight UTC. The same instant as `X-Daily-Reset`.
    - `mcp` object: Usage through the hosted MCP server, a subset of the requests above.
      - `usedThisMonth` integer: Calls made through the MCP server in the reported month. Already counted in `currentMonth.used`, never on top of it.
      - `usedToday` integer: MCP calls today (UTC) across every key on the account.
      - `dailyLimitPerKey` integer: MCP calls one key may make per UTC day on this plan. The limit applies to each key separately.
      - `busiestKeyToday` object, nullable: The key nearest its daily MCP limit, or null when no key has made an MCP call today.
        - `keyId` string: Id of the key closest to its MCP limit today.
        - `keyName` string: The label you gave the key.
        - `used` integer: MCP calls that key made today.
        - `percentage` integer: Share of `dailyLimitPerKey` that key has used, rounded.
      - `resetsAt` string: When the daily MCP counters return to zero: the next midnight UTC.
    - `progress` object: Your standing. Experience is earned per call and weighted by what the call is: resolving a name, asking what fits a firearm or comparing two records is worth several times a page of a list, because the point is integration depth rather than traffic. Earned by an SDK, the MCP server, a script or a request tool; a browser earns nothing, since the reference has a Try It button and a page left open should not outrank a production service. A `304` earns nothing, on the same reasoning that it spends no quota, and a call that failed earns nothing either.
      - `xp` integer: Experience earned across every key on the account, for its whole life.
      - `xpToday` integer: Experience earned today (UTC).
      - `dailyXpCap` integer: The most one key can earn in a UTC day. A ceiling rather than a target: reaching it every day is not how the levels are meant to be climbed.
      - `level` integer: Your level, derived from `xp` alone. Nothing else moves it.
      - `levelStartsAt` integer: The experience this level began at.
      - `nextLevelAt` integer: The experience the next level begins at.
      - `streakDays` integer: Consecutive days you have called the API, counting today. A day you did not call breaks it, though yesterday still counts as unbroken so a timezone does not cost you a streak. Reported, never rewarded: no experience is paid for showing up.
      - `daysActive` integer: Days you have called the API at all, over the last two years.
      - `operationsUsed` integer: Documented operations you have called at least once. Counted from the request log by the nightly job, so an operation you called for the first time today appears tomorrow.
      - `operationsAvailable` integer: Documented operations there are to call, counted from this document rather than written down, so it cannot fall behind a route added today.
    - `endpointCredits` object: Calls to endpoints above your plan, attached to the account so every key draws on the same balance. Every new account starts with a one-time grant covering any endpoint up to Studio, and the team can give more. A call spent this way is served exactly as the endpoint's own plan would be (full fields, that plan's paging depth), is marked with an `X-Endpoint-Credit: spent` header, and still counts against your plan's per-minute and daily limits. A call that fails, or answers `304`, is given back.
      - `remaining` integer: Calls left across every credit that can still be spent.
      - `credits` object[]: Every credit the account has had, newest first, spent ones included.
        - `id` string: Id of the credit.
        - `source` string: `welcome` for the one-time grant every account receives, `staff` for a credit the team gave you.
        - `operations` string[], nullable: The operations it covers, or null when it covers everything up to `maxTier`.
        - `maxTier` string, nullable: The highest plan whose endpoints it covers, or null when it names operations.
        - `callsGranted` integer: Calls the credit was given.
        - `callsUsed` integer: Calls spent so far.
        - `callsRemaining` integer: Calls left on it. Zero once it is spent, expired or withdrawn.
        - `expiresAt` string, nullable: When it lapses, ISO 8601 UTC, or null when it does not.
        - `status` string: `active`, `spent`, `expired` or `revoked`.
        - `createdAt` string: When it was given.
    - `dailyBreakdown` object[]: Requests per day over the reported period, oldest first. Days with no traffic are omitted.
      - `date` string: The day, `YYYY-MM-DD` in UTC.
      - `count` integer: How many records fall in this bucket.
      - `mcpCount` integer: Of `count`, the requests made through the MCP server.
    - `perKey` object[]: Requests per API key over the reported period.
      - `keyId` string: Id of the API key. The key itself is never returned.
      - `keyName` string: The label you gave the key.
      - `count` integer: How many records fall in this bucket.
      - `mcpCount` integer: Of `count`, the requests made through the MCP server.
      - `mcpToday` integer: MCP calls this key made today (UTC), the figure its daily MCP limit is held against.
      - `today` integer: Requests this key made today (UTC), the figure its daily limit is held against. Counts calls the limit refused.
      - `remainingToday` integer, nullable: Requests this key has left today, never below zero. Null when the plan has no daily ceiling.
    - `keyCount` integer: How many API keys the account holds.
    - `tier` object: The allowances of the plan the account is on.
      - `name` string: Display name, as the maker writes it.
      - `requestsPerMonth` integer: Monthly request allowance on this plan, enforced for the whole account.
      - `requestsPerDay` integer, nullable: Requests each key may make per UTC day on this plan: the limit that is enforced. Null when the plan has no daily ceiling.
      - `rateLimit` integer: Requests per minute this plan allows.
      - `mcpCallsPerDay` integer: MCP calls each key may make per UTC day on this plan.

## Other responses

- `400`: Validation error
- `401`: Missing or invalid API key
- `403`: The credential is valid and the caller is not permitted. Three causes, none of which reissuing a key changes: the plan is below the endpoint's tier, the account is suspended, or the key is not attached to the thing being acted on, meaning a user account for `/v1/me` or a shop for `/v1/vendor`. Distinct from 401, which means the credential is missing, malformed or expired and a new one can work.
- `429`: A limit was reached. `RATE_LIMITED` is the per-minute limit: wait `Retry-After` seconds (a minute) and retry. `DAILY_CAP_EXCEEDED` is the plan's daily limit, per key: nothing will be served until the counters return to zero at midnight UTC. `MONTHLY_CAP_EXCEEDED` is the plan's monthly allowance, for the whole account: nothing will be served until midnight UTC on the first of next month, or until the plan changes. For both, `Retry-After` is the seconds until then and `error.resetsAt` says when as an instant. Calls made after a refusal are refused too and do not spend the month, and a free key that keeps calling is paused, so stop at the first one and resume at the reset.
- `500`: Internal server error

---

[API](https://skmtc.dev/gunspec/apis/gunspec-io-api.md) · [All operations](https://skmtc.dev/gunspec/apis/gunspec-io-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gunspec/apis/gunspec-io-api/revisions/f2e974d8b05c?raw)