Developer recipe

Export creator search results to CSV with Python

Create a CSV of up to 500 US fitness creators with published contact emails. Limit the job to five search pages, deduplicate by pk and stop when the response has no more rows.

Get your free API keyRead the docs
Job budget
50 credits
Request cap
5 searchs
Interface
Python · REST

The workflow

  1. Set a bounded request budget

    Five pages at 100 records each means at most 500 rows before deduplication and 50 search credits. This is a cap for the sample script, not a promise that 500 creators match.

  2. Export only the fields your workflow needs

    Keep pk as the stable identifier and write CSV using a real CSV library so commas and quotes in bios cannot corrupt columns. The example also neutralizes spreadsheet formula prefixes.

  3. Import and review the list

    Map pk, username and extracted_email into your CRM, and deduplicate subsequent imports on pk. A published email is not a deliverability check. This recipe creates a local file; it does not send outreach.

Example request

cURL
curl --fail-with-body "https://api.ugcroster.com/v1/creators/search" \
  -H "Authorization: Bearer $ROSTER_API_KEY" \
  -G \
  --data-urlencode "niche=fitness" \
  --data-urlencode "country=US" \
  --data-urlencode "has_email=true" \
  --data-urlencode "sort=followers" \
  --data-urlencode "limit=100"

Set ROSTER_API_KEY in your environment. Keep the key on your server. This command requests one page.

Example request, not a live benchmark. A data key covers search and profile reads. Campaign writes require a Roster brand key.

Export up to five pages

Install Python’s requests package, set ROSTER_API_KEY and run this script. It writes creators.csv in your working directory.

creators.csv · bounded exportPython
import csv
import os
import time
import requests

headers = {"Authorization": f"Bearer {os.environ['ROSTER_API_KEY']}"}
params = {"niche": "fitness", "country": "US", "has_email": "true",
          "sort": "followers", "limit": 100}
fields = ["pk", "username", "follower_count", "extracted_email", "country"]
seen = set()

def spreadsheet_safe(value):
    text = str(value) if value is not None else ""
    if text.lstrip().startswith(("=", "+", "-", "@", "\t", "\r", "\n")):
        return "'" + text
    return text

with open("creators.csv", "w", newline="", encoding="utf-8") as output:
    writer = csv.DictWriter(output, fieldnames=fields)
    writer.writeheader()
    for page in range(1, 6):  # At most 5 requests / 50 search credits.
        response = requests.get(
            "https://api.ugcroster.com/v1/creators/search",
            headers=headers, params={**params, "page": page}, timeout=30)
        response.raise_for_status()  # Stop; do not retry indefinitely.
        payload = response.json()
        rows = payload["data"]
        for row in rows:
            if row["pk"] in seen:
                continue
            seen.add(row["pk"])
            writer.writerow({key: spreadsheet_safe(row.get(key)) for key in fields})
        if len(rows) < 100 or page * 100 >= payload["pagination"]["total"]:
            break
        time.sleep(1.1)  # Allow for other traffic sharing your key's limit.

Price the job before you build.

5 search requests × 10 credits + 0 profile reads × 1 credit = 50 credits at the five-page cap.

Allocated workflow cost at full use of each plan’s monthly credits
PlanMonthly subscriptionAllocated job cost*
Starter$98$0.1960
Growth$398$0.1327
Scale$998$0.0998

Prepaid alternative: $0.2500 worth of credits for this request budget, purchased in packs starting at $25 for 5,000 credits. No monthly subscription; 60 requests/minute. Auto-reload is optional. This is credit consumption, not a per-call checkout.

*Monthly subscription price divided by included credits, multiplied by this job’s credits. These are illustrative allocations assuming full use of the allowance, not standalone pay-per-call checkout prices. You still pay the subscription. Extra purchased credits, tax and retries are excluded.

Calculate your monthly workload

Keep building