> ## Documentation Index
> Fetch the complete documentation index at: https://docs.repdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate Limits & Polling

> Recommended polling cadence and best practices for keeping allocations and quotas in sync.

The Supply API is designed to be polled. Allocations, qualifications, and quotas change throughout fieldwork — for example, a quota may close when it paces ahead of plan, or an allocation may be reassigned if a supplier underperforms. Polling keeps your platform in sync so you only send respondents to open targets.

## Recommended Polling Cadence

| Endpoint                                                                                                                                                                                                                                     | Recommended Cadence                        |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| [List Surveys & Streams](https://docs.repdata.com/supply/endpoints/get-v2-surveys)                                                                                                                                                           | Every 2–3 minutes                          |
| [Get Stream Quotas](https://docs.repdata.com/supply/endpoints/get-v2-surveys-streams-StreamNumber-quotas)                                                                                                                                    | Every 2–3 minutes                          |
| [Languages](https://docs.repdata.com/supply/endpoints/get-v2-languages) · [Countries](https://docs.repdata.com/supply/endpoints/get-v2-countries) · [Qualification Library](https://docs.repdata.com/supply/endpoints/get-v2-qualifications) | Infrequently (cache and refresh as needed) |

Rather than re-reading every Stream on each poll, use the `QualificationsLastChangedTimestamp` and `QuotasLastChangedTimestamp` fields on the Surveys response to detect which Streams changed and refresh only those.

<Note>
  In-field metrics warm up with volume: `ActualLOI` and `ActualIR` are initially calculated after **20 completes**.
</Note>

## Pausing Sample

Use the `Remaining` (Surveys) and `QuotaRemaining` (Quotas) fields as your primary indicators of whether more respondents are needed. When a value reaches `0`, pause sample to that Stream or quota cell.

## Best Practices

<CardGroup cols={2}>
  <Card title="Detect changes by timestamp" icon="clock-rotate-left">
    Compare `QualificationsLastChangedTimestamp` and `QuotasLastChangedTimestamp` between polls and refresh only the Streams that changed.
  </Card>

  <Card title="Cache lookup data" icon="database">
    Languages, countries, and the qualification library change infrequently. Cache them and refresh on a schedule rather than per request.
  </Card>

  <Card title="Respect closed cells" icon="circle-pause">
    When `Remaining` or `QuotaRemaining` hits `0`, stop sending to that Stream or quota cell to avoid over-delivery.
  </Card>

  <Card title="Test in staging" icon="flask">
    Run integration and load testing against staging (`https://stage-api.researchdesk.com`) before pointing traffic at production.
  </Card>
</CardGroup>

<Tip>
  If you see a rate card higher than $100 CPI, alert the Supply team and pause sample to that Stream. There is no hard maximum CPI, but consumer projects should not typically exceed $40.
</Tip>