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

# Stream Polling

> Poll SEC API stream events with cursor checkpoints, make processing idempotent, and recover safely after a worker failure.

Use cursor polling when your worker cannot receive a public webhook or when it needs explicit replay checkpoints. Create and change stream subscriptions in the signed-in dashboard; use an API key only to read the events after the subscription exists.

## Poll one bounded batch

```bash theme={null}
curl --fail-with-body -H "x-api-key: $SECAPI_API_KEY" \
  "https://api.secapi.ai/v1/stream_subscriptions/str_123/events?limit=25" \
  | jq '{data, nextCursor, replayCursor, requestId, traceparent}'
```

The response contains ordered `data`, `nextCursor` for the next read, and `replayCursor` for durable checkpoint recovery. Expected output is a bounded event batch; no event means the worker should wait and poll again according to its own schedule.

## Commit only after work succeeds

For every event, store the event id in the same transaction that creates downstream work. Only then store the returned cursor. On the next run, send that stored cursor:

```bash theme={null}
curl --fail-with-body -H "x-api-key: $SECAPI_API_KEY" \
  "https://api.secapi.ai/v1/stream_subscriptions/str_123/events?cursor=$SECAPI_STREAM_CURSOR&limit=25"
```

Cursor order is recorded event order, not a filing timestamp. Use the server-returned cursor, never the last array position, a wall-clock time, or an accession number as a checkpoint.

## Recover and operate

If processing fails halfway through a batch, leave the checkpoint unchanged and rerun idempotently. If a worker is behind, reduce the batch size and drain progressively rather than skipping to a newer cursor. Retain subscription id, event id, cursor, request id, traceparent, and any cited filing identifiers in each run log.

Use [Webhook and stream workflows](/webhook-stream-workflows) to choose the right delivery mode. Configuration, endpoint changes, and replay policy remain human-authenticated dashboard work.