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, docs.api.market)

Base URL

https://prod.api.market/api/v1

All paths below are appended to this base.

Authentication

Pass your personal or workspace API key in the custom x-magicapi-key request header. This keyed-header scheme follows the same convention used by AWS API Gateway and other major providers. (Swagger, Stoplight)

x-magicapi-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, Microsoft Learn)
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-magicapi-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)

Example Request (cURL)

curl -X GET \
  'https://prod.api.market/api/v1/user/usage/magicapi/faceswap-v2/' \
  -H 'x-magicapi-key: YOUR_API_MARKET_KEY' \
  -H 'accept: application/json'

Example Response

{
  "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	<store>/<product> 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

import requests, os

API_KEY = os.getenv("API_MARKET_KEY")
url = "https://prod.api.market/api/v1/user/usage/magicapi/faceswap-v2/"
headers = {
    "x-magicapi-key": API_KEY,
    "accept": "application/json"
}
resp = requests.get(url, headers=headers, timeout=10)
resp.raise_for_status()
print(resp.json()["apiCallsLeft"])

const res = await fetch(
  "https://prod.api.market/api/v1/user/usage/magicapi/faceswap-v2/",
  {
    method: "GET",
    headers: {
      "x-magicapi-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

curl -X GET 'https://prod.api.market/api/v1/user/usage/' \
  -H 'x-magicapi-key: YOUR_API_MARKET_KEY' \
  -H 'accept: application/json'

Example Response (truncated)

{
  "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-magicapi-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)
• 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)
• Rotate keys: Treat the x-magicapi-key like a password; rotate periodically and immediately on suspected compromise. (Stack Overflow)
• Follow REST conventions when embedding the endpoint in client SDKs for long-term stability. (Stack Overflow Blog)

---

Changelog

Date	Change
2025-05-17	Initial public release

---

Happy building!