A social insights API for ad generation platforms. It provides structured signals, like psychographics, behavioral insights, trends, and audience language, to help AI models generate relevant, higher-converting ads.
Search for brands that recently sponsored media channels/publications.
Provide exactly one scope filter: categories or publication_url.
categories: Find sponsors active in those content verticals.publication_url: Find sponsors for a specific creator/publication.Use platforms, date range, and confidence parameters to refine results.
Content-vertical phrases or keywords (e.g. 'consumer tech', 'startup tools', 'personal finance'). Not brand or company names. Free-form strings are normalized to our standard category taxonomy and used to scope the search. Mutually exclusive with publication_url.
A creator's publication URL (YouTube channel, Substack newsletter, podcast, etc.) to find its sponsors. Mutually exclusive with categories.
Platforms to include when searching for sponsors. If omitted, results include all available platforms.
Minimum sponsorship confidence threshold
Maximum number of results per page. Requesting more than 20 results requires a credits-based plan.
Pagination cursor from next_cursor. To continue a paginated activity request, pass it with the same filters and omit activity_after and sync_token.
Include structured evidence for the most recent ad (source, excerpt, and transcript offset when available)
Only return sponsors with a placement whose sponsor_type is one of these values. When omitted, defaults to ['explicit_ad', 'implicit_ad', 'affiliate', 'promotion', 'unknown']. Other valid values include: 'merch_store', 'self_promotion'.
Alternate name for sponsor_types; accepts one or more values.
Time window in days (default 90). Ignored when since is provided.
Start date (YYYY-MM-DD, inclusive). Overrides days_back. Required when until is provided.
End date (YYYY-MM-DD, inclusive). Defaults to today when only since is provided.
Sort order for results. 'total_ads' (default) ranks brands by number of placements. 'recent' ranks by most recent ad date. For activity searches, these rank only sponsorships in the requested activity.
Start a sponsor activity request after this ISO-8601 datetime. Requires platforms. Earlier values use the first supported activity time. For later requests, save next_sync_token from a response and send it as sync_token.
Opaque checkpoint returned as next_sync_token by an earlier activity request. Use it instead of activity_after to start the next request.
curl https://api.upriver.ai/v1/sponsors \
--header 'X-API-Key: YOUR_SECRET_TOKEN'
{
"results": [
{
"partner_name": "Microsoft",
"sponsor_id": "br_0123456789abcdef",
"sponsor_domain": "microsoft.com",
"sponsor_linkedin_url": "https://www.linkedin.com/company/microsoft",
"sponsor_description": "string",
"total_ads_found": 5,
"sponsorships_in_window": 1,
"most_recent_ad": {
"publication_name": "TechCrunch",
"publication_url": "https://techcrunch.com",
"publication_categories": [
"technology",
"startups"
],
"publication_platform": "substack",
"content_url": "https://example.com/article",
"sponsor_type": "explicit_ad",
"monetization_type": "paid_partnership",
"disclosure_tier": "platform_verified",
"published_date": "2024-03-15",
"evidence": {
"source": "transcript",
"excerpt": "...thanks to Acme for sponsoring today's video--use code GADGET for 10%...",
"offset_seconds": 92.5,
"confidence": 0.88
}
}
}
],
"total_count": 1,
"industry_category": "string",
"next_cursor": "string",
"has_more": false,
"next_sync_token": "string"
}