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

# Poll for new sponsorships

> Use a saved sync token to fetch sponsorship activity without repeatedly loading the same history.

Use activity requests when you periodically fetch sponsorships added to
Upriver. Start once with a timestamp, then save the returned sync token for
later requests.

You can poll [List sponsorships](/sponsorships/sponsorships) for individual
placements or [List sponsors](/sponsorships/sponsors) for results grouped by
sponsor name.

## Before you start

Choose the following before your first request:

* A scope filter supported by the endpoint, such as `sponsor_id`,
  `sponsor_name`, `categories`, or `publication_url`.
* One or more explicit platforms: `youtube`, `instagram`, `podcast`,
  `substack`, or `tiktok`.
* A durable place to save `next_sync_token`.

Activity polling uses the same publication-date filters as an ordinary list
request. `since`, `until`, and `days_back` filter when content was published;
they do not determine where activity polling resumes. If you omit them, the
endpoint uses its default rolling 90-day lookback. You can change these filters
when starting a later poll with `sync_token`; keep them unchanged only while
following `next_cursor`. Usually omit `until` so later polls can include newly
published content.

## Poll for activity

<Steps>
  <Step title="Start with a timestamp">
    Send `activity_after` as an ISO 8601 timestamp with a timezone offset:

    ```bash theme={null}
    curl --get 'https://api.upriver.ai/v1/sponsorships' \
      --header 'X-API-Key: YOUR_API_KEY' \
      --data-urlencode 'sponsor_name=Notion' \
      --data-urlencode 'platforms=youtube' \
      --data-urlencode 'activity_after=2026-08-23T10:00:00Z' \
      --data-urlencode 'limit=50'
    ```

    The response includes a page cursor when more results are available and a
    sync token for starting the next poll:

    ```json theme={null}
    {
      "results": [
        {
          "sponsor_id": "br_01hzy8k9m4qp7v2wxr3d5abcde",
          "sponsor_name": "Notion"
        }
      ],
      "next_cursor": "apg1...",
      "has_more": true,
      "next_sync_token": "ast1..."
    }
    ```
  </Step>

  <Step title="Process the results you want">
    To process every result, follow `next_cursor` with the same filters. Omit
    `activity_after` and `sync_token` while paging:

    ```bash theme={null}
    curl --get 'https://api.upriver.ai/v1/sponsorships' \
      --header 'X-API-Key: YOUR_API_KEY' \
      --data-urlencode 'sponsor_name=Notion' \
      --data-urlencode 'platforms=youtube' \
      --data-urlencode 'cursor=apg1...' \
      --data-urlencode 'limit=50'
    ```

    Continue until `has_more` is `false`. Do not change filters, platforms,
    publication dates, or sort order between pages.

    If you only want the highest-ranked results from each poll, process the
    first page and intentionally leave the remaining pages behind. The same
    `next_sync_token` appears on every page.
  </Step>

  <Step title="Save the sync token">
    After successfully processing the pages you intend to keep, save
    `next_sync_token`. If processing fails, retain your previously saved token
    or current page cursor and retry without advancing.
  </Step>

  <Step title="Start the next poll">
    Send the saved value as `sync_token`:

    ```bash theme={null}
    curl --get 'https://api.upriver.ai/v1/sponsorships' \
      --header 'X-API-Key: YOUR_API_KEY' \
      --data-urlencode 'sponsor_id=br_01hzy8k9m4qp7v2wxr3d5abcde' \
      --data-urlencode 'platforms=youtube' \
      --data-urlencode 'sync_token=ast1...' \
      --data-urlencode 'limit=50'
    ```

    Treat the token as opaque. Do not decode, edit, or construct it yourself.
  </Step>
</Steps>

## Choose complete delivery or top results

The page cursor and sync token support different workflows:

* Use `next_cursor` to continue through the current set of results.
* Use `next_sync_token` to move to the next poll, leaving any remaining pages
  behind.

For complete delivery, save the sync token only after the final page. For a
cost-controlled monitoring workflow, you can save it after processing the
first page or any other stopping point you choose.

## Delivery and billing

A sponsorship appears in activity when it is first added to Upriver. Later
corrections, deletions, or changes that make an older placement eligible are
outside this feed.

An empty result is valid and still includes `next_sync_token`. Save it to avoid
searching the same interval again.

Existing result-based prices apply to every request. Retries and overlapping
workers can return and charge for the same rows again. Run one worker for a
given page cursor, and advance the saved sync token only after processing the
results you intend to keep.

See [Sponsor names and IDs](/sponsorships/sponsor-identifiers) before building
saved sponsor filters or deduplication.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.