Skip to main content
Use activity windows when you poll for new sponsorship discoveries. Each window returns placements first detected after your starting time and through the end time reported by the API. The interval is:
You can use activity windows with List sponsorships for placement rows or List sponsors for results grouped by sponsor name.

​
Before you start

Choose all of the following before the first request:
  • A scope filter such as sponsor_id, sponsor_name, categories, or publication_url, depending on the endpoint.
  • One or more explicit platforms: youtube, instagram, podcast, substack, or tiktok.
  • A fixed since date for the publication history you want to monitor.
  • A durable place to save the final activity_window.through time.
since and until filter when content was published. activity_after filters when Upriver first detected a placement. They answer different questions and can be used together.
For ongoing polling, always send the same explicit since date. If you omit it, the default publication window moves forward over time, and content can age out before a newly detected placement is delivered. Usually omit until so each new completed poll can include newly published content. Set until only when you intentionally want a permanent upper bound.

​
Fetch a complete activity window

1

Start with activity_after

Send an ISO 8601 time with a timezone offset. This example finds new YouTube placements for a known sponsor name:
Every activity response includes its effective interval:
If your requested time predates activity tracking, the response’s after shows the effective start time used by the API.
2

Follow every page cursor

When has_more is true, send next_cursor with the same filters. Omit activity_after; the cursor already identifies the window.
Continue until has_more is false. Do not change filters, platforms, publication dates, or sort order between pages.
3

Save the final through time

The final page has no next_cursor:
After you successfully process the whole final page, save activity_window.through.
4

Use the through time for the next poll

Send the saved time as activity_after:
The next window starts after the previous window’s through time.

​
Switch from a sponsor name to sponsor_id

Use sponsor_name as a convenience when you initially know only a brand’s external name. When a result includes sponsor_id, store it as the canonical identifier for later sponsor-specific searches, saved filters, and deduplication. Finish all pages of the name-based window first. Then start a new ID-based window from the prior response’s activity_window.through:
Finish the name-based window before changing filters so the saved through time does not introduce a gap. Page cursors remain bound to the filters that produced them.

​
Use sponsor summary activity

GET /v1/sponsors follows the same cursor and timestamp workflow. During an activity search:
  • new_placements_in_window counts newly detected placements for that sponsor name.
  • last_detected_at reports the latest detection in the window.
  • sort_by=total_ads ranks by new_placements_in_window.
  • sort_by=recent ranks by last_detected_at.
The endpoint keeps its name-based grouping, so two results can share one sponsor_id. Use sponsor_id to recognize that they represent the same brand.

​
Delivery and billing behavior

Activity means first detection only. A later correction, deletion, or change that makes an older placement match your filters does not create new activity. The API does not provide a correction feed or maintain a permanent list of which sponsors your account has seen. Existing result-based prices apply to rows returned by each request. Retries and overlapping workers can return and charge for the same rows again. Process one page at a time for a given cursor. Persist activity_window.through only after the final page has been processed.

​
Troubleshooting

Use the same endpoint, filters, platforms, publication dates, and sort order that produced it. Also omit activity_after while following a page cursor.
Your requested start is later than the activity currently available, or a pinned page is temporarily unavailable. Keep your saved time or cursor and retry later.
Activity is not currently available through every required ingestion path for that platform. Keep your prior activity time and retry later. Contact support if the response persists.
An empty window is valid. Save activity_window.through and use it as the next activity_after so you do not search the same interval again.