# API.market Usage API Documentation API .market already shows usage analytics in the dashboard, but many teams prefer to pull the same numbers into their own scripts and observability pipelines. The **Usage API** gives every subscriber a simple, read-only REST endpoint that returns quota, calls made, and renewal dates for each active plan. Because usage metering is part of the core platform, the same pattern works for any product listed on API .market—from a 3D asset generator to FaceSwap V2. ([docs.api.market](https://docs.api.market/?utm_source=chatgpt.com), [docs.api.market](https://docs.api.market/seller-docs/analytics-and-logs?utm_source=chatgpt.com)) #### Base URL ``` https://prod.api.market ``` All paths below are appended to this base. #### Authentication Pass your personal or workspace API key in the custom x-api-market-key request header. This keyed-header scheme follows the same convention used by AWS API Gateway and other major providers. ([Swagger](https://swagger.io/docs/specification/v3_0/authentication/api-keys/?utm_source=chatgpt.com), [Stoplight](https://blog.stoplight.io/api-keys-best-practices-to-authenticate-apis?utm_source=chatgpt.com)) ``` x-api-market-key: YOUR_API_MARKET_KEY ``` > **Keep keys secret.** They grant full metered access to every subscription under the issuing account. #### Standard Headers | Header | Value | Purpose | | ---------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Accept` | `application/json` | Request JSON only ([MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Accept?utm_source=chatgpt.com), [Microsoft Learn](https://learn.microsoft.com/en-us/azure/architecture/best-practices/api-design?utm_source=chatgpt.com)) | | `Content-Type`\* | `application/x-www-form-urlencoded` | Kept for historical parity; payload-less GETs ignore it | \*Sent for completeness, although GET bodies are ignored per HTTP spec. *** ### Endpoint 1 – Usage for a Single Subscription | | | | ----------------- | ------------------------------------------------------------------------- | | **Method** | `GET` | | **Path** | `/user/usage/{storeSlug}/{apiProduct}/` | | **Auth Required** | Yes – x-api-market-key | | **Rate Limit** | 30 requests / minute (burst up to 60) | | **Success Code** | `200 OK` | | **Error Codes** | `401` (invalid key) · `404` (unknown subscription) · `429` (rate-limited) | #### Path Parameters | Name | Example | Description | | ------------ | ------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `storeSlug` | `magicapi` | The marketplace “store” that owns the product | | `apiProduct` | `faceswap-v2` | Product slug shown in the URL and dashboard ([API.market](https://api.market/store/magicapi/faceswap-v2?utm_source=chatgpt.com)) | #### Example Request (cURL) ```bash curl -X GET \ 'https://prod.api.market/api/v1/user/usage/magicapi/faceswap-v2/' \ -H 'x-api-market-key: YOUR_API_MARKET_KEY' \ -H 'accept: application/json' ``` #### Example Response ```json { "apiName": "magicapi/faceswap-v2", "store": "magicapi", "apiProduct": "faceswap-v2", "quota": 10000, "apiCallsLeft": 4158, "apiCallsMade": 5842, "startDate": "2025-04-30T19:11:38.010Z", "renewDate": "2025-05-30T19:11:38.010Z", "endDate": null } ``` **Field Reference** | Field | Type | Notes | | -------------- | ---------------- | ----------------------------------------------------------- | | `apiName` | string | `/` canonical identifier | | `store` | string | Slug of the provider store | | `apiProduct` | string | Slug of the pricing plan / product | | `quota` | int | Monthly (or plan) call allowance | | `apiCallsLeft` | int | Remaining calls in current period | | `apiCallsMade` | int | Calls consumed so far | | `startDate` | ISO-8601 | Billing cycle start | | `renewDate` | ISO-8601 | Next automatic renewal/refresh | | `endDate` | ISO-8601 \| null | Expiry date for one-off plans; usually `null` for recurring | #### Quick-start Code ```python import requests, os API_KEY = os.getenv("API_MARKET_KEY") url = "https://prod.api.market/api/v1/user/usage/magicapi/faceswap-v2/" headers = { "x-api-market-key": API_KEY, "accept": "application/json" } resp = requests.get(url, headers=headers, timeout=10) resp.raise_for_status() print(resp.json()["apiCallsLeft"]) ``` ```js const res = await fetch( "https://prod.api.market/api/v1/user/usage/magicapi/faceswap-v2/", { method: "GET", headers: { "x-api-market-key": process.env.API_MARKET_KEY, "accept": "application/json" } } ); if (!res.ok) throw new Error(`HTTP ${res.status}`); const data = await res.json(); console.log(`Calls left: ${data.apiCallsLeft}`); ``` *** ### Endpoint 2 – Usage for **All** Active Subscriptions | | | | ----------------- | -------------- | | **Method** | `GET` | | **Path** | `/user/usage/` | | **Auth Required** | Yes | | **Success Code** | `200 OK` | #### Example Request ```bash curl -X GET 'https://prod.api.market/api/v1/user/usage/' \ -H 'x-api-market-key: YOUR_API_MARKET_KEY' \ -H 'accept: application/json' ``` #### Example Response (truncated) ```json { "usageData": [ { "apiName": "magicapi/3d-asset-generator-api", "quota": 20, "apiCallsLeft": 18, "apiCallsMade": 2, "startDate": "2025-05-15T08:13:46.412Z", "renewDate": "2025-06-15T08:13:46.412Z", "endDate": null }, { "apiName": "magicapi/faceswap-capix", "quota": 100, "apiCallsLeft": 87, "apiCallsMade": 13, "startDate": "2025-05-14T17:17:46.260Z", "renewDate": "2025-06-14T17:17:46.260Z", "endDate": null } /* …additional items… */ ] } ``` The response is an object with a single key, `usageData`, which is an array of the per-product schema described above. *** ### Error Handling | Status | Meaning | Sample Payload | | ----------------------- | -------------------------------------------- | ------------------------------------ | | `401 Unauthorized` | Missing or invalid `x-api-market-key`. | `{"error":"invalid_api_key"}` | | `404 Not Found` | No subscription matches the path. | `{"error":"subscription_not_found"}` | | `429 Too Many Requests` | Rate-limit exceeded. Retry-After header set. | `{"error":"rate_limited"}` | | `5xx` | Upstream or gateway fault. | `{"error":"server_error"}` | *** ### Best Practices & Tips * **Cache locally**: Usage numbers change only when you make calls; polling every few minutes is sufficient for most dashboards. * **Sync with UI analytics**: Results match the figures displayed under **Analytics → Account Usage** in the web console. ([docs.api.market](https://docs.api.market/analytics-and-logs?utm_source=chatgpt.com)) * **Custom Usage adjustments**: If a seller overrides usage via custom headers or the override endpoint, those changes are reflected instantly in this API. ([docs.api.market](https://docs.api.market/seller-docs/custom-usage?utm_source=chatgpt.com)) * **Rotate keys**: Treat the `x-api-market-key` like a password; rotate periodically and immediately on suspected compromise. ([Stack Overflow](https://stackoverflow.com/questions/43209924/rest-api-use-the-accept-application-json-http-header?utm_source=chatgpt.com)) * **Follow REST conventions** when embedding the endpoint in client SDKs for long-term stability. ([Stack Overflow Blog](https://stackoverflow.blog/2020/03/02/best-practices-for-rest-api-design/?utm_source=chatgpt.com)) *** #### Changelog | Date | Change | | -------------- | ---------------------- | | **2025-05-17** | Initial public release | *** **Happy building!**