--- title: "Check shared usage" method: GET path: "/v1/usage" tags: ["Account"] --- # Check shared usage `GET /v1/usage` ## Request - Base URL: `https://tcgdata-api.ottenniels1999.workers.dev` - URL: `https://tcgdata-api.ottenniels1999.workers.dev/v1/usage` - Auth: HTTP bearer Current billing-period and UTC-day request usage shared by every key and game. Free tests receive 500 requests once for 30 days, one active key, 10 requests/minute and batches of 10 IDs. Free usage stays in its original bucket across month boundaries; resets_at is the test expiry and never replenishes the budget. This call consumes one request, including the current call in the totals, and is blocked when the monthly, daily or minute limit is exhausted. New accounts reset on their monthly activation anniversary in UTC; migrated accounts keep calendar-month periods. Plan changes and new keys never reset usage. Counters for catalogue, history, images and bytes are diagnostic. Deprecated credits fields are not a separate quota. The envelope includes upgrade: null, or an upgrade suggestion when this call exhausts the monthly or daily allowance. Published plans link to the account page and activate automatically after Stripe confirms payment. Custom access requires a separate agreement and manual activation. Opening a suggestion does not change access or charge the account. 1 admitted HTTP request. Unknown query/body parameters are rejected. Examples contain illustrative data and placeholder IDs; they are not live catalogue records. ## Response `200` Success. 1 admitted HTTP request. - UsageResponse - `data` Usage, required - `credits` integer, required: Historical successful-request telemetry. Not a quota and not equal to admitted requests; use requests and request_limit. - `reserved_credits` integer: Deprecated in-flight telemetry retained for older clients. It does not reduce the request allowance. - `requests` integer, required: Admitted HTTP requests in the billing period or fixed one-time free-test bucket, including this usage call and admitted errors. - `period` string, date, required: First UTC date of the current billing period, or the free-test start date. - `day` string, date: UTC date of the current daily request counter. - `billing_cycle` 'calendar' | 'anniversary', required: Paid billing-cycle bookkeeping. Free tests keep one fixed bucket and never renew at these boundaries. - `billing_anchor_date` string, date, nullable, required - `daily_requests` integer, required - `daily_limit` integer, required - `daily_remaining` integer, required - `daily_resets_at` string, date-time, required - `batch_size` integer, required - `limit` integer, required: Alias of request_limit: admitted HTTP requests allowed per billing period. - `remaining` integer, required: Alias of requests_remaining, including this usage call. - `heavy_requests` integer, required - `catalogue_requests` integer, required - `history_requests` integer, required - `image_requests` integer, required - `response_bytes` integer, required - `request_limit` integer, required - `requests_remaining` integer, required - `heavy_request_limit` integer, required - `heavy_requests_remaining` integer, required - `image_request_limit` integer, required - `image_requests_remaining` integer, required - `response_bytes_limit` integer, required - `response_bytes_remaining` integer, required - `resets_at` string, date-time, required: Paid allowance reset, or free-test expiry. A free test never renews at this timestamp. - `upgrade` UpgradeNotice, required: Upgrade suggestion for an authenticated account that reached a request limit or whose free test expired. Free tests recommend Starter and never renew; resets_at is their expiry, not a renewal. Paid accounts can wait for the applicable reset. recommended_plan is null when no suitable higher published plan is known. No automatic charge. - `activation` 'payment' | 'manual', required: Published plans activate after Stripe confirms payment; custom access requires an agreement and manual activation. - `reason` 'monthly_request_limit' | 'daily_request_limit' | 'rate_limited' | 'trial_expired', required - `message` string, required - `current_plan` string, nullable, required - `recommended_plan` UpgradePlan, required - `id` string, required - `name` string, required - `monthly_eur` number, required: Monthly EUR price excluding VAT. A proposal, not an automatic charge. - `currency` 'EUR', required - `monthly_requests` integer, required - `daily_requests` integer, required - `requests_per_minute` integer, required - `batch_size` integer, required - `request_url` string, required: Root-relative account plan-selection or custom-access contact path on https://tcgdata.dev. Opening it does not activate or charge for a plan. - `resets_at` string, date-time, required ## Other responses - `400`: Invalid request or batch_size_exceeded (more IDs than the account plan allows) - `401`: Invalid or missing key - `403`: Inactive account, expired free test or resource_limits_unconfigured - `404`: Not found or unavailable - `405`: Wrong method - `409`: Ambiguous printing or variant - `413`: Oversized request body or response_too_large (response exceeds 1 MiB) - `415`: Wrong content type - `429`: Monthly, UTC-daily or minute request limit; authenticated account limits include a paid-plan or custom-access upgrade suggestion. Defensive resource-limit errors retain the ordinary error envelope. - `503`: Disabled, unconfigured or temporarily unavailable --- [API](https://skmtc.dev/tcgdata/apis/tcgdata-dev-multi-game-prices-and-daily-history.md) · [All operations](https://skmtc.dev/tcgdata/apis/tcgdata-dev-multi-game-prices-and-daily-history/llms.txt) · [OpenAPI document](https://skmtc.dev/tcgdata/apis/tcgdata-dev-multi-game-prices-and-daily-history/revisions/1db91fd8a408?raw)