API Reference

CuteMarkets uses a tiered subscription model. Options and stocks are separate subscription products, but both use the same plan ladder, throughput rules, freshness rules, lookback windows, and quote gating.

Plans

Products

Options and stocks are purchased independently. Keep using tier for the Options API subscription and stock_tier for the Stocks API subscription in profile responses.

• A Developer options plan does not unlock stock access unless you also subscribe to Developer or higher for stocks.
• A stock Expert plan unlocks stock quotes, not options quotes.
• API keys are product-scoped. Use an Options API key for options endpoints and a Stocks API key for stock endpoints.

Historical lookback

Each plan enforces a hard limit on how far back in time you can query. Requests that include a date or timestamp parameter that falls outside your plan's window are rejected with a 403 lookback_exceeded error.

The cutoff is calculated relative to the time of the request (rolling window, not a fixed calendar year).

Example 403 Response

curl \
  "https://api.cutemarkets.com/v1/options/contracts/?underlying_ticker=SPY&as_of=2020-01-01" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "status": "ERROR",
  "request_id": "cm_9c4a1d82e3f04b6a8d2e7f1c5b0a9e3d",
  "error": {
    "code": "lookback_exceeded",
    "message": "Your Free plan allows up to 3 years of historical lookback. Upgrade your plan to access older data."
  }
}

Rate limit headers

Every API response includes headers that tell you your current usage:

Example 429 Response

If you exceed your plan's request limit, you'll receive an ERROR envelope like this:

curl \
  "https://api.cutemarkets.com/v1/options/chain/NFLX/?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "status": "ERROR",
  "request_id": "cm_f38efe47d6b24bf691281cb973a60b61",
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Upgrade your plan for higher limits."
  }
}

Capacity planning

Plan limits should be designed into the client before traffic increases. A dashboard that requests one snapshot every few seconds has a very different usage profile from a backfill job that pages through historical quotes for hundreds of contracts. Estimate requests per workflow, then decide which jobs can run interactively and which should run in a queue.

Free plans have fixed per-minute and per-day limits, so clients should avoid bursty fan-out. Paid plans remove the listed request caps, but the integration should still use bounded concurrency, pagination discipline, and retry safety. Unlimited plan limits are not a reason to create unbounded workers; they are a way to avoid artificial throttling for normal production workloads.

Backoff and retry policy

Only retry errors that are safe to repeat. 429 rate_limit_exceeded can be retried later with backoff. Most 400, 401, 403, and 404 responses should not be retried blindly because they usually indicate a parameter, entitlement, credential, lookback, or lifecycle issue. Retrying those errors wastes quota and can hide the real problem.

For background jobs, keep the original request and page cursor with the job record. If a cursor expires or becomes invalid, restart from the base query and follow the new next_url values. Do not synthesize cursor values in client code.

Product-key planning

Options and stocks are separate products. A team that uses both should name keys clearly, separate environment variables, and test one endpoint from each product during deployment. A common production mistake is using an Options API key for a stock quote endpoint or a Stocks API key for an options chain. The error response will identify the failure, but the prevention belongs in configuration.

Suggested environment naming:

CUTEMARKETS_OPTIONS_API_KEY=...
CUTEMARKETS_STOCKS_API_KEY=...

When a workflow joins stock context to option contracts, pass the correct key to each endpoint family and log the product label with the request id. That makes entitlement and lookback issues much faster to diagnose.