Guides

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 for individual placements or List 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

Start with a timestamp

Send activity_after as an ISO 8601 timestamp with a timezone offset:

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:

{
  "results": [
    {
      "sponsor_id": "br_01hzy8k9m4qp7v2wxr3d5abcde",
      "sponsor_name": "Notion"
    }
  ],
  "next_cursor": "apg1...",
  "has_more": true,
  "next_sync_token": "ast1..."
}

Process the results you want
To process every result, follow next_cursor with the same filters. Omit activity_after and sync_token while paging:
Terminal window
```
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.
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.

Start the next poll

Send the saved value as sync_token:

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.

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 before building saved sponsor filters or deduplication.