Plans & Limits

Pricing is published on predictorsdk.com/pricing. This page is the developer-facing summary: how throughput limits work, which tier each endpoint requires, and how to read plan data programmatically. For the machine-readable version, hit GET /v1/plans — no auth required.

Plans at a glance

• Monthly allowance applies per UTC calendar month.
• Rate limit is a per-key rolling 60-second ceiling. Pace from the response's Retry-After and X-RateLimit-Reset headers rather than assuming a particular server-side algorithm.
• Overage only applies to paid plans. Free is a hard cap (see below).

Endpoint availability

Both sports matching routes — the list and the lookup, settled history (include_settled=true) included — resolve to the same tier gate, and each request counts once against your allowance. See the filtering and pagination guides for how the modes differ in request shape and response.

Free plan cap

Free is the only tier with a hard monthly ceiling — there is no overage. The cap is 1,000 authenticated request attempts per UTC calendar month on authenticated endpoints. "Attempt" means the call is counted before the handler runs, so failed or malformed requests still consume allowance. When the cap is reached, all authenticated calls return 402 Payment Required with action: upgrade_plan for the rest of the month.

The 402 response body includes included_requests_per_month and current_period_requests so clients can show remaining allowance without a separate call. See Error Handling for the full 402 response shape.

Reading plans programmatically

GET /v1/plans returns the full catalog — prices, allowances, features — as JSON. No auth required. This is what the pricing page renders from, so it stays in sync automatically.

curl https://api.predictorsdk.com/v1/plans

The response shape:

{
  "data": [
    {
      "key": "free",
      "name": "Free",
      "billing_tier": "free",
      "monthly_price_cents": 0,
      "included_requests_per_month": 1000,
      "overage_cents_per_1k": 0,
      "rate_limit_per_min": 10,
      "max_keys": 1,
      "features": ["Sports matching (list with league, date and participant filters, lookup by identifier, ...)", "..."],
      "contact_sales": false
    }
  ]
}

Stripe price IDs are stripped from the public response.

The generated clients expose the same unauthenticated operation:

const catalog = await client.getPlans();

Python uses client.get_plans() and Go uses client.GetPlans(ctx).

When you hit 402

If a request comes back with 402, read required_tier from the body and route the user to /pricing (or show an in-app upgrade prompt). The action field distinguishes "upgrade to a higher plan" from "your existing subscription needs a payment fix" — handle both with a single switch in your error handler. The Error Handling guide has example code for each SDK.