Rate Limits & Quotas

Every finlight API key is bound to a plan, and the plan defines your usage limits and which capabilities you can access. Limits are enforced per API key, in real time. This page explains each limit and what each plan unlocks; for the exact numbers on your plan, see the finlight dashboard or the pricing page.

The four usage limits

  • Name
    Monthly request quota
    Description

    Each REST request consumes one request from your monthly allowance. The counter resets at the start of every billing period. Exceeding it returns 429 with "Exceeded token limit of N for the current period."

  • Name
    Burst rate
    Description

    A short-term limit on requests per 10 seconds, smoothing spikes. Only enforced on plans that define it. Exceeding it returns 429 with "Exceeded rate limit of N requests per 10 seconds." — back off ~10s and retry.

  • Name
    WebSocket connections
    Description

    The maximum number of concurrent WebSocket connections for your key. New connections beyond the limit are rejected. A separate cap limits the total number of streamed messages per period. WebSocket requires a paid plan.

  • Name
    Webhook delivery quota
    Description

    The maximum number of webhook deliveries per billing period. A companion limit caps how many webhooks you can create. When the delivery quota is exhausted, deliveries pause until the next period.

Capabilities unlocked by your plan

Beyond raw limits, your plan controls which features are available. Requesting a feature your plan doesn't include returns 403 (for REST) or simply omits the data (for webhooks/WebSocket).

  • Name
    Historical data
    Description

    How far back you can query depends on your plan. The Free and Pro Light plans currently cover roughly the last month of articles; higher plans unlock deeper historical coverage. Use the from / to date filters to query within your plan's window — requests for dates outside it simply return no results for that range. See the pricing page for each plan's exact history window.

  • Name
    Sentiment analysis
    Description

    Includes the sentiment and confidence fields on articles. Stripped from payloads when not granted.

  • Name
    Company entities
    Description

    Includes the companies array (AI-resolved tickers, ISIN, exchange, etc.) and enables includeEntities. Stripped when not granted.

  • Name
    Custom sources
    Description

    Private or customer-specific news sources added to your default set. Available on higher / enterprise plans.

How enforcement works

  • Per key, in real time. Each request increments your counters; once a limit is crossed the API returns 429 immediately.
  • Dashboard usage isn't live. The usage shown in the finlight dashboard is aggregated about once a day and reflects activity through the previous day — it is not a real-time counter. Enforcement is live, so your actual remaining quota for today can differ from what the dashboard shows.
  • Monthly counters reset at the start of your billing period — a quota 429 clears automatically.
  • No rate-limit headers. finlight does not currently send Retry-After or X-RateLimit-* headers. Treat a burst 429 as "wait ~10 seconds"; treat a monthly 429 as "quota reached for this period." See Errors & Status Codes.

Plans

PlanTypical use
FreeEvaluation and low-volume use. REST only (no WebSocket).
Pro (Light / Standard / Scale)Production workloads with increasing quotas, WebSocket, webhooks, and richer enrichment.
EnterpriseHigh volume, custom sources, and bespoke limits.

Exact numeric limits (monthly tokens, burst rate, WebSocket connections, webhook quota) and the feature set per plan are part of pricing and can change. Always check your current plan's limits in the finlight dashboard, or compare plans on the pricing page. Need higher limits or custom sources? Contact us.

When you hit a limit

  • Burst 429 → pause ~10 seconds, then continue.
  • Monthly quota 429 → you've used your period's requests; upgrade, or wait for the reset.
  • WebSocket connection rejected → you're at your concurrent-connection cap; close an idle connection (see the takeover option in WebSocket Quickstart).
  • Webhook deliveries paused → your delivery quota for the period is exhausted; it resumes next period.
  • 403 on a feature → that capability isn't in your plan; see the table above.

For the exact error bodies, see Errors & Status Codes.