Sponsors

GET

sponsors

cURL

curl -X GET 'https://api.upriver.ai/v1/sponsors?industry=tech' \
  -H 'X-API-Key: YOUR_API_KEY'

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.upriver.ai/v1/sponsors', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.upriver.ai/v1/sponsors",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.upriver.ai/v1/sponsors"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.upriver.ai/v1/sponsors")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "results": [
    {
      "partner_name": "Microsoft",
      "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
        }
      },
      "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": 123
    }
  ],
  "total_count": 123,
  "industry_category": "<string>",
  "next_cursor": "<string>",
  "has_more": false,
  "next_sync_token": "<string>"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Use this endpoint to find brands that have sponsored creators. Each result groups the matching placements under one sponsor name and includes summary counts plus the most recent placement. A sponsor can appear in more than one result when its name is spelled differently. Those results can share a sponsor_id; when it is present, use that ID to identify the same sponsor across name variants. See Sponsor names and IDs for the recommended workflow. For an activity request, sponsorships_in_window reports how many sponsorships for that name appear in the requested window. Use the count to decide whether to load individual rows from List sponsorships. The most recent placement includes monetization_type, disclosure_tier, and the legacy sponsor_type label. To see every sponsored post, use List sponsorships. See Sponsorship types for field definitions and differences between Instagram and TikTok labels. To poll for sponsor activity without repeatedly loading the same history, see Poll for new sponsorships.

Authorizations

X-API-Key

string

header

required

Query Parameters

categories

string[] | null

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.

Maximum array length: 3

Example:

["consumer tech", "startup tools"]

publication_url

string | null

A creator's publication URL (YouTube channel, Substack newsletter, podcast, etc.) to find its sponsors. Mutually exclusive with categories.

Example:

"https://techweekly.substack.com"

platforms

enum<string>[] | null

Platforms to include when searching for sponsors. Repeat this parameter to provide multiple values. If omitted, results include all available platforms.

Available options:

beehiiv,

ghost,

instagram,

newsletter,

podcast,

substack,

tiktok,

youtube

Example:

["substack", "podcast"]

confidence_threshold

number

default:0.5

Minimum sponsorship confidence threshold

Required range: 0 <= x <= 1

limit

integer

default:20

Maximum number of results per page. Requesting more than 20 results requires a credits-based plan.

Required range: 1 <= x <= 50

cursor

string | null

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_evidence

boolean

default:false

Include structured evidence for the most recent ad (source, excerpt, and transcript offset when available)

sponsor_types

string[] | null

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'.

Example:

[
  "explicit_ad",
  "implicit_ad",
  "affiliate",
  "promotion",
  "unknown"
]

sponsor_type

string[] | null

Alternate name for sponsor_types; accepts one or more values.

days_back

integer

default:90

Time window in days (default 90). Ignored when since is provided.

Required range: 1 <= x <= 365

since

string | null

Start date (YYYY-MM-DD, inclusive). Overrides days_back. Required when until is provided.

until

string | null

End date (YYYY-MM-DD, inclusive). Defaults to today when only since is provided.

sort_by

enum<string>

default:total_ads

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.

Available options:

total_ads,

recent

activity_after

string | null

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.

sync_token

string | null

Opaque checkpoint returned as next_sync_token by an earlier activity request. Use it instead of activity_after to start the next request.

Response

Successful Response

Response for simplified partner search by industry

results

SimplifiedPartnerSearchResult · object[]

required

List of partner content results

Show child attributes

total_count

integer

required

Number of results in the current page (not a grand total)

industry_category

string | null

The industry category searched

next_cursor

string | null

Cursor for fetching the next page of results

has_more

boolean

default:false

Whether there are more results available

next_sync_token

string | null

Token for starting the next sponsor activity request. Save it after processing the results from this response that you intend to keep. Returned only for activity searches.

⌘I

cURL

curl -X GET 'https://api.upriver.ai/v1/sponsors?industry=tech' \
  -H 'X-API-Key: YOUR_API_KEY'

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.upriver.ai/v1/sponsors', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.upriver.ai/v1/sponsors",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.upriver.ai/v1/sponsors"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.upriver.ai/v1/sponsors")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "results": [
    {
      "partner_name": "Microsoft",
      "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
        }
      },
      "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": 123
    }
  ],
  "total_count": 123,
  "industry_category": "<string>",
  "next_cursor": "<string>",
  "has_more": false,
  "next_sync_token": "<string>"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

API Reference

Guides

Agents + LLMs

Updates

Authorizations

Query Parameters

Response