SparkToro API Documentation

01Getting started

The SparkToro API exposes the same audience-research engine that powers the SparkToro app. You build an audience report from a natural-language prompt — "B2B SaaS founders in the US who write on LinkedIn" — and then pull section data (demographics, websites, podcasts, etc.) using the report_id it returns.

Every request needs an API key sent as a Bearer token. Get one from your API dashboard.

Your first call

Confirm your key works by hitting the credits endpoint — it's free and returns your current balance.

curl

curl "https://api.sparktoro.com/v3/account/credits" \
  -H "Authorization: Bearer YOUR_API_KEY"

200 OK

{
  "credits_remaining": 4000,
  "credits_expires_at": "2027-05-01T00:00:00Z",
  "is_trial": false,
  "low_balance": false,
  "rate_limit_per_min": 60
}

02Authentication

Every API request must include your API key as a Bearer token in the Authorization header. Keys are scoped to your account; treat them like a password.

header

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx

Where to get a key

Your API dashboard shows your active keys, lets you create new ones, and lets you revoke compromised keys. Keys never expire on their own — you control their lifecycle.

Keep keys server-side

Never embed an API key in client-side JavaScript or mobile apps. Anyone who can read the binary can steal the key. Call the SparkToro API from your backend.

03Credits & metering

Every billable endpoint costs a fixed number of credits. Your plan includes a monthly allowance that resets at the start of each billing period; unused credits do not roll over.

How credits are debited

Credits are charged at request dispatch, before the work runs. If the request returns a 5xx error the charge is automatically refunded.
You're charged once per (endpoint, report_id) per billing period — re-pulling the same section for the same report is free for the rest of the period.
Creating an audience report (POST /v3/describe/create) charges 10 credits regardless of how many sections you later request.

Checking your balance

Hit GET /v3/account/credits at any time — it's free and returns your plan allowance, credits used this period, and credits remaining.

Hitting the wall

When you run out of credits, the next billable request returns a 402 Insufficient credits response with the cost and your remaining balance. No partial charges, no debit row written.

04Rate limits

To keep the service responsive for everyone, requests are capped per minute per account:

Account	Limit
Trial	10 requests / minute
Paid	60 requests / minute

Hitting the limit returns 429 Too Many Requests with a Retry-After header (seconds until the next minute bucket). Need a higher ceiling? Email support@sparktoro.com and we can raise it per account.

05Endpoints

All endpoints share the base URL https://api.sparktoro.com and respond with JSON. Required parameters are marked.

Account

GET /v3/account/credits # Free

Get current credit balance

Free (0 credits). Returns the caller's remaining credits, expiration date, trial status, low-balance flag, and per-minute rate limit.

Example request

curl

curl -X GET "https://api.sparktoro.com/v3/account/credits" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response fields

Field	Type	Description
credits_remaining	`integer`	Credits available to spend right now.
credits_expires_at	`string (date-time)` nullable	When the entire balance expires. Resets to 12 months from purchase on every new pack. Null only on accounts that have never been topped up.
is_trial	`boolean`	True until the account makes its first paid pack purchase. Trial accounts start with 200 credits and a lower default rate limit.
low_balance	`boolean`	True when credits_remaining is below the account's low-balance threshold (default 500, overridable per-account).
rate_limit_per_min	`integer`	Max requests per minute for this account. Defaults: 10 trial, 60 paid. May be raised on request.

Responses

200 Current balance.

Show example response

json

{
    "credits_remaining": 0,
    "credits_expires_at": "2026-01-01T00:00:00Z",
    "is_trial": true,
    "low_balance": true,
    "rate_limit_per_min": 0
}

GET /v3/reports # Free

List reports (free)

Free (0 credits). Lists reports created via the public API for the authenticated account, newest first. Paginate with limit and scroll: pass the scroll token from one response as ?scroll= on the next request. A null scroll in the response means you've reached the last page. Reports created in the SparkToro app are not included.

Parameters

Name	In	Type	Required	Description
limit	query	integer	optional	Number of reports per page (1-100, default 50).Default: `50`Range: min 1, max 100
scroll	query	string	optional	Opaque pagination cursor from a previous response's `scroll` field. Omit for the first page.

Example request

curl

curl -X GET "https://api.sparktoro.com/v3/reports" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -G --data-urlencode "report_id=YOUR_REPORT_ID"

Response fields

Field	Type	Description
reports	`array<ReportListItem>`
scroll	`string` nullable	Cursor for the next page. Null when there are no more results.

Responses

200 One page of reports.

Show example response

json

{
    "reports": [
        {
            "report_id": "string",
            "name": "string",
            "prompt": "string",
            "created_at": "2026-01-01T00:00:00Z"
        }
    ],
    "scroll": "string"
}

400 Invalid scroll token.

Show example response

json

{
    "error": true,
    "status": 0,
    "message": "string"
}

Audience reports

POST /v3/describe/create # 10 credits

Create an audience report

Costs 10 credits. Creates the report synchronously (typically 10-20 seconds) and returns a report_id you pass to the section endpoints. The report_id is queryable immediately; individual sections build on first request, and derived sections (Reddit, Brands, Prompts) return 202 while building — see each section's 202 response.

Request body

Field	Type	Required	Description
prompt	string	required	Natural-language audience description (people, not topics). e.g. B2B SaaS founders in the US who write on LinkedIn.
location	string	optional	Options: `us`, `ca`, `uk`Default: `us`

Example request

curl

curl -X POST "https://api.sparktoro.com/v3/describe/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"B2B SaaS founders in the US","location":"us"}'

Response fields

Field	Type	Description
report_id	`string`	Stable handle for the report. Pass it as ?report_id= to every section endpoint.
status	`string`	Always 'ready'. This is report-level: it confirms the report has been created and its audience is resolved. It does NOT mean every section is built. Section data is assembled on first request, and sections derived from other parts of the report (Reddit, Brands, Prompts) return 202 while building. Treat each section's own 200 response — not this status — as the signal that its data is complete.Options: `ready`
message	`string`	Human-readable confirmation or error detail.

Responses

200 Report created (the call runs synchronously, typically 10-20 seconds). 'ready' here is report-level: the report and its audience exist and you can begin querying sections. It does not mean every section is built. Section data is assembled on first request — primary sections (Websites, Keywords, Demographics, Social) return 200 immediately, while sections derived from other parts of the report (Reddit, Brands, Prompts) return 202 while building; retry those until they return 200 (only the first request per section is charged, so retries are free). Pass the returned report_id to any section endpoint.

Show example response

json

{
    "report_id": "string",
    "status": "ready",
    "message": "string"
}

People

GET /v3/demographics # 1 credit

Demographics

Returns audience demographics as an object of named sub-arrays (age, gender, industry, title_role, education_majors, city, state, ...). Long-tail fields (industry, title_role, school_name, skills, education_majors, department, city, state, country) respect ?limit=N; categorical fields (age, gender, years_experience, married, children, homeowner, education_degree, etc.) are always returned in full because capping them would drop legitimate categories. Use ?fields=key1,key2 to narrow the response to specific keys.

Parameters

Name	In	Type	Required	Description
report_id	query	string	required	Report identifier returned by POST /v3/describe/create.
limit	query	integer	optional	Cap on the number of items returned. Narrows the response but never exceeds the endpoint's default cap.Default: `300`Range: min 1, max 300
fields	query	string	optional	Comma-separated list of top-level demographic keys to return (e.g. `age,gender,industry`). Unknown keys are silently dropped. Omit to return all fields.

Example request

curl

curl -X GET "https://api.sparktoro.com/v3/demographics" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -G --data-urlencode "report_id=YOUR_REPORT_ID"

Response fields

Field	Type	Description
data	`object`	Object-of-arrays keyed by demographic field name. Each value is an array of {name, value} buckets sorted by value descending. Categorical fields (age, gender, salary, net_worth, married, children, homeowner, years_experience, education_degree, education_degree_type, company_revenue, company_employee_count, country) return their full bucket set; long-tail fields (title_role, department, industry, school_name, skills, education_majors, city, state) respect ?limit=N (default 50). Use ?fields=age,gender to return only specific fields. The state field's buckets additionally include population_baseline.

Plus a standard meta object with credits_charged and credits_remaining.

Responses

200 OK

Show example response

json

{
    "data": [],
    "meta": {
        "credits_charged": 0,
        "credits_remaining": 0,
        "credits_expires_at": "2026-01-01T00:00:00Z",
        "low_balance": true
    }
}

GET /v3/bios # 5 credits

Keywords from audience bios

Parameters

Name	In	Type	Required	Description
report_id	query	string	required	Report identifier returned by POST /v3/describe/create.
limit	query	integer	optional	Cap on the number of items returned. Narrows the response but never exceeds the endpoint's default cap.Default: `300`Range: min 1, max 300
history	query	string	optional	When `false`, the per-item `history` map is omitted from the response. Default `true`. When included, history is always trimmed to the most recent 12 months.Options: `true`, `false`Default: `true`

Example request

curl

curl -X GET "https://api.sparktoro.com/v3/bios" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -G --data-urlencode "report_id=YOUR_REPORT_ID"

Response item fields

Field	Type	Description
keyword	`string`	Keyword extracted from audience bios/profiles.
affinity	`number`	This audience's affinity for the keyword (0-100).
history	`object`	Monthly trend object keyed by YYYY-MM.

Plus a standard meta object with credits_charged and credits_remaining.

Responses

200 OK

Show example response

json

{
    "data": [
        {
            "keyword": "string",
            "affinity": 0,
            "history": []
        }
    ],
    "meta": {
        "credits_charged": 0,
        "credits_remaining": 0,
        "credits_expires_at": "2026-01-01T00:00:00Z",
        "low_balance": true
    }
}

Channels they use

GET /v3/websites # 2 credits

Top websites visited

Parameters

Name	In	Type	Required	Description
report_id	query	string	required	Report identifier returned by POST /v3/describe/create.
limit	query	integer	optional	Cap on the number of items returned. Narrows the response but never exceeds the endpoint's default cap.Default: `300`Range: min 1, max 300
history	query	string	optional	When `false`, the per-item `history` map is omitted from the response. Default `true`. When included, history is always trimmed to the most recent 12 months.Options: `true`, `false`Default: `true`

Example request

curl

curl -X GET "https://api.sparktoro.com/v3/websites" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -G --data-urlencode "report_id=YOUR_REPORT_ID"

Response item fields

Field	Type	Description
id	`integer`	SparkToro's internal numeric domain id; a stable join key across endpoints.
domain	`string`	The website's domain (e.g. gartner.com).
affinity	`number`	This audience's affinity for the site (0-100).
category	`string`	IAB-style content category for the domain.
visits	`integer`	Estimated total monthly panel visits to this domain.
moz_da	`integer`	Moz Domain Authority (0-100).
moz_links	`integer`	Backlink count from Moz.
hidden_gem	`boolean`	High-affinity, low-popularity flag.
history	`object`	Monthly trend object keyed by YYYY-MM.
meta_description	`string` nullable	Short site description from the domain's meta tags.

Plus a standard meta object with credits_charged and credits_remaining.

Responses

200 OK

Show example response

json

{
    "data": [
        {
            "id": 0,
            "domain": "string",
            "affinity": 0,
            "category": "string",
            "visits": 0,
            "moz_da": 0,
            "moz_links": 0,
            "hidden_gem": true,
            "history": [],
            "meta_description": "string"
        }
    ],
    "meta": {
        "credits_charged": 0,
        "credits_remaining": 0,
        "credits_expires_at": "2026-01-01T00:00:00Z",
        "low_balance": true
    }
}

GET /v3/websites/categories # 2 credits

Top website categories visited

Aggregated IAB-category roll-up of the same websites returned by /v3/websites. Useful for understanding the audience's content interests at a higher level than individual domains. Returns the tier-1 breakdown by default; pass an item's iab_id back as ?iab_id= to drill into its subcategories. Pricing: the top-level view costs 2 credits; each distinct subcategory drilldown costs 1 credit. Both de-dupe per report — re-fetching the same view or the same subcategory doesn't charge again.

Parameters

Name	In	Type	Required	Description
report_id	query	string	required	Report identifier returned by POST /v3/describe/create.
iab_id	query	string	optional	IAB Content Taxonomy category id to drill into. Every item in the tier-1 response carries an `iab_id`; pass one back here to get the next-deeper subcategory breakdown within it (e.g. `iab_id=52` for "Business and Finance"). Omit for the top-level breakdown. An unknown id returns 400. Each distinct subcategory drilldown costs 1 credit (deduped per report + subcategory).
limit	query	integer	optional	Cap on the number of items returned. Narrows the response but never exceeds the endpoint's default cap.Default: `300`Range: min 1, max 300

Example request

curl

curl -X GET "https://api.sparktoro.com/v3/websites/categories" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -G --data-urlencode "report_id=YOUR_REPORT_ID"

Response item fields

Field	Type	Description
iab_id	`string` nullable	IAB Content Taxonomy category id for this bucket. Pass it back as `?iab_id=` to drill into its subcategories. Null on the synthetic "Other" and "Unclassified" buckets.
iab_tier	`string`	The category's own name at this level (e.g. "Business and Finance", "Industries").
iab_hierarchy	`string`	Full taxonomy path to this category (e.g. "Business and Finance > Industries").
domain_count	`integer`	Number of the audience's websites that fall in this category.
sample_size	`integer`	Alias of domain_count; the sample behind the metrics (low values mean the over-index can swing on a single site).
score_share	`number` nullable	Share of the audience's total website attention spent in this category. Null on the Unclassified bucket.
country_baseline_share	`number` nullable	The typical country panel-user's share of attention in this category. Null when no country baseline exists yet.
over_index	`number` nullable	score_share / country_baseline_share — how much more (or less) this audience concentrates here vs the country average.
top_domains	`array<object>`	Up to 5 top websites in this category for the audience, by affinity.

Plus a standard meta object with credits_charged and credits_remaining.

Responses

200 OK

Show example response

json

{
    "data": [
        {
            "iab_id": "string",
            "iab_tier": "string",
            "iab_hierarchy": "string",
            "domain_count": 0,
            "sample_size": 0,
            "score_share": 0,
            "country_baseline_share": 0,
            "over_index": 0,
            "top_domains": [
                {
                    "domain_normal": "string",
                    "score": 0
                }
            ]
        }
    ],
    "meta": {
        "credits_charged": 0,
        "credits_remaining": 0,
        "credits_expires_at": "2026-01-01T00:00:00Z",
        "low_balance": true
    }
}

GET /v3/social # 2 credits

Top social accounts followed

Parameters

Name	In	Type	Required	Description
report_id	query	string	required	Report identifier returned by POST /v3/describe/create.
limit	query	integer	optional	Cap on the number of items returned. Narrows the response but never exceeds the endpoint's default cap.Default: `300`Range: min 1, max 300

Example request

curl

curl -X GET "https://api.sparktoro.com/v3/social" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -G --data-urlencode "report_id=YOUR_REPORT_ID"

Response item fields

Field	Type	Description
id	`string`	Twitter numeric id.
username	`string`	Account handle (without the @).
name	`string`	Display name.
description	`string`	Account bio.
profile_image	`string (uri)`	Avatar image URL.
relationships	`object`	Maps a network name (facebook, instagram, twitter, linkedin, domain, …) to the linked account(s) on that network. Item fields vary by network: `type` and `username` are always present; `user_id` appears for SparkToro-known accounts, `clean_domain` only on the `domain` entry (the account's own website).
followers	`integer`	Follower count on this network.
following	`integer`	Number of accounts this account follows.
global_followers	`integer`	Aggregate follower count across all of this account's known networks.
sparkscore	`number`	SparkToro engagement metric (0-100).
engagement_score	`number`	Per-account engagement signal.
affinity	`number`	This audience's affinity for the account (0-100).
location	`string` nullable	Free-text location from the account profile (often empty).
verified	`integer`	1 if the account is verified on its network, else 0.
hidden_gem	`boolean`	High-affinity, low-following flag.
website	`string (uri)`	Account's own website URL.

Plus a standard meta object with credits_charged and credits_remaining.

Responses

200 OK

Show example response

json

{
    "data": [
        {
            "id": "string",
            "username": "string",
            "name": "string",
            "description": "string",
            "profile_image": "https://example.com",
            "relationships": [],
            "followers": 0,
            "following": 0,
            "global_followers": 0,
            "sparkscore": 0,
            "engagement_score": 0,
            "affinity": 0,
            "location": "string",
            "verified": 0,
            "hidden_gem": true,
            "website": "https://example.com"
        }
    ],
    "meta": {
        "credits_charged": 0,
        "credits_remaining": 0,
        "credits_expires_at": "2026-01-01T00:00:00Z",
        "low_balance": true
    }
}

GET /v3/networks # 1 credit

Social networks usage

Social platforms / networks the audience uses (Facebook, YouTube, Twitter, TikTok, LinkedIn, Reddit, etc.).

Parameters

Name	In	Type	Required	Description
report_id	query	string	required	Report identifier returned by POST /v3/describe/create.
limit	query	integer	optional	Cap on the number of items returned. Narrows the response but never exceeds the endpoint's default cap.Default: `300`Range: min 1, max 300
history	query	string	optional	When `false`, the per-item `history` map is omitted from the response. Default `true`. When included, history is always trimmed to the most recent 12 months.Options: `true`, `false`Default: `true`

Example request

curl

curl -X GET "https://api.sparktoro.com/v3/networks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -G --data-urlencode "report_id=YOUR_REPORT_ID"

Response item fields

Field	Type	Description
domain	`string`	The network/platform domain (e.g. youtube.com).
category	`string`	IAB-style content category for the domain.
visits	`integer`	Estimated total monthly panel visits to this domain.
current_rank	`integer`	Rank within this audience.
affinity	`number`	This audience's usage of the domain (0-100).
country_average	`number`	Country-baseline usage of the domain (0-100).
affinity_lift	`number`	How much the audience over/under-indexes the baseline (affinity − country_average), rounded to 2 decimals.
history	`object`	Monthly trend object keyed by YYYY-MM.
meta_description	`string` nullable	Short description from the domain's meta tags.

Plus a standard meta object with credits_charged and credits_remaining.

Responses

200 OK

Show example response

json

{
    "data": [
        {
            "domain": "string",
            "category": "string",
            "visits": 0,
            "current_rank": 0,
            "affinity": 0,
            "country_average": 0,
            "affinity_lift": 0,
            "history": [],
            "meta_description": "string"
        }
    ],
    "meta": {
        "credits_charged": 0,
        "credits_remaining": 0,
        "credits_expires_at": "2026-01-01T00:00:00Z",
        "low_balance": true
    }
}

GET /v3/youtube # 1 credit

Top YouTube channels

Parameters

Name	In	Type	Required	Description
report_id	query	string	required	Report identifier returned by POST /v3/describe/create.
limit	query	integer	optional	Cap on the number of items returned. Narrows the response but never exceeds the endpoint's default cap.Default: `300`Range: min 1, max 300
history	query	string	optional	When `false`, the per-item `history` map is omitted from the response. Default `true`. When included, history is always trimmed to the most recent 12 months.Options: `true`, `false`Default: `true`

Example request

curl

curl -X GET "https://api.sparktoro.com/v3/youtube" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -G --data-urlencode "report_id=YOUR_REPORT_ID"

Response item fields

Field	Type	Description
id	`string`	YouTube's channel id (e.g. UCtinbF-Q-fVthA0qrFQTgXQ). Use with the YouTube Data API or to construct channel URLs.
channel_url	`string (uri)`	Canonical YouTube channel URL.
title	`string`	Channel name.
affinity	`number`	This audience's affinity for the channel (0-100).
image	`string (uri)`	Channel avatar/thumbnail URL.
subscribers	`integer`	Subscriber count.
views	`integer`	Total lifetime channel views.
average_views	`integer`	Average views per video.
join_date	`string (date)`	Channel creation date (YYYY-MM-DD).
latest_video	`string (date)`	Date of the most recent video (YYYY-MM-DD).
description	`string`	Channel description from YouTube.

Plus a standard meta object with credits_charged and credits_remaining.

Responses

200 OK

Show example response

json

{
    "data": [
        {
            "id": "string",
            "channel_url": "https://example.com",
            "title": "string",
            "affinity": 0,
            "image": "https://example.com",
            "subscribers": 0,
            "views": 0,
            "average_views": 0,
            "join_date": "2026-01-01",
            "latest_video": "2026-01-01",
            "description": "string"
        }
    ],
    "meta": {
        "credits_charged": 0,
        "credits_remaining": 0,
        "credits_expires_at": "2026-01-01T00:00:00Z",
        "low_balance": true
    }
}

GET /v3/podcasts # 1 credit

Top podcasts listened to

Returns the podcasts this audeince listens to.

Parameters

Name	In	Type	Required	Description
report_id	query	string	required	Report identifier returned by POST /v3/describe/create.
limit	query	integer	optional	Cap on the number of items returned. Narrows the response but never exceeds the endpoint's default cap.Default: `300`Range: min 1, max 300

Example request

curl

curl -X GET "https://api.sparktoro.com/v3/podcasts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -G --data-urlencode "report_id=YOUR_REPORT_ID"

Response item fields

Field	Type	Description
id	`string`	Apple Podcasts iTunes collection id (e.g. 1200361736). Use with Apple's Lookup API or to construct podcast URLs like https://podcasts.apple.com/us/podcast/id{id}.
title	`string`	Show title.
affinity	`number`	This audience's affinity for the show (0-100).
author	`string`	Show author / publisher.
category	`string`	Apple Podcasts category (e.g. Business, Technology).
episodes	`integer`	Total number of published episodes.
stars	`number`	Apple Podcasts rating (1-5), rounded to 2 decimals.
review_count	`integer`	Number of Apple Podcasts ratings.
link	`string (uri)`	Apple Podcasts URL.
website	`string (uri)`	The show's own website.
artwork	`string (uri)`	Cover artwork image URL.
recent_date	`string (date)`	Date of the most recent episode (YYYY-MM-DD).
description	`string`	Show description.

Plus a standard meta object with credits_charged and credits_remaining.

Responses

200 OK

Show example response

json

{
    "data": [
        {
            "id": "string",
            "title": "string",
            "affinity": 0,
            "author": "string",
            "category": "string",
            "episodes": 0,
            "stars": 0,
            "review_count": 0,
            "link": "https://example.com",
            "website": "https://example.com",
            "artwork": "https://example.com",
            "recent_date": "2026-01-01",
            "description": "string"
        }
    ],
    "meta": {
        "credits_charged": 0,
        "credits_remaining": 0,
        "credits_expires_at": "2026-01-01T00:00:00Z",
        "low_balance": true
    }
}

GET /v3/reddit # 2 credits

Top subreddits visited

Parameters

Name	In	Type	Required	Description
report_id	query	string	required	Report identifier returned by POST /v3/describe/create.
limit	query	integer	optional	Cap on the number of items returned. Narrows the response but never exceeds the endpoint's default cap.Default: `300`Range: min 1, max 300

Example request

curl

curl -X GET "https://api.sparktoro.com/v3/reddit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -G --data-urlencode "report_id=YOUR_REPORT_ID"

Response item fields

Field	Type	Description
display_name	`string`	Subreddit slug.
title	`string`	Subreddit display title.
description	`string`	Subreddit public description.
subscribers	`integer`	Subscriber count.
url	`string (uri)`	Absolute Reddit URL.
affinity	`number`	This audience's affinity for the subreddit (0-100).
lang	`string`	Primary language code (e.g. 'en').
over18	`integer`	0/1 NSFW flag.
private	`integer`	0/1 flag for whether the subreddit is private.
created_at	`string (date-time)`	Subreddit creation timestamp (UTC).
reddit_id	`string`	Reddit's own id (e.g. '2qhcs').

Plus a standard meta object with credits_charged and credits_remaining.

Responses

200 OK

Show example response

json

{
    "data": [
        {
            "display_name": "string",
            "title": "string",
            "description": "string",
            "subscribers": 0,
            "url": "https://example.com",
            "affinity": 0,
            "lang": "string",
            "over18": 0,
            "private": 0,
            "created_at": "2026-01-01T00:00:00Z",
            "reddit_id": "string"
        }
    ],
    "meta": {
        "credits_charged": 0,
        "credits_remaining": 0,
        "credits_expires_at": "2026-01-01T00:00:00Z",
        "low_balance": true
    }
}

202 This section is derived from other parts of the report that have not been built yet. The request has started that build in the background — retry in a few seconds and it will return 200. Only the first request for a section is charged, so retries are free.

Show example response

json

{
    "error": true,
    "status": 0,
    "message": "string"
}

GET /v3/press # 2 credits

Press / media outlets read

News + media outlets the audience reads (NBC, CBS, Wall Street Journal, NYT, etc.).

Parameters

Name	In	Type	Required	Description
report_id	query	string	required	Report identifier returned by POST /v3/describe/create.
limit	query	integer	optional	Cap on the number of items returned. Narrows the response but never exceeds the endpoint's default cap.Default: `300`Range: min 1, max 300
history	query	string	optional	When `false`, the per-item `history` map is omitted from the response. Default `true`. When included, history is always trimmed to the most recent 12 months.Options: `true`, `false`Default: `true`

Example request

curl

curl -X GET "https://api.sparktoro.com/v3/press" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -G --data-urlencode "report_id=YOUR_REPORT_ID"

Response item fields

Field	Type	Description
domain	`string`	The media outlet's domain (e.g. nytimes.com).
affinity	`number`	This audience's affinity for the outlet (0-100).
visits	`integer`	Estimated total monthly panel visits to this domain.
moz_da	`integer`	Moz Domain Authority (0-100).
moz_links	`integer`	Backlink count from Moz.
history	`object`	Monthly trend object keyed by YYYY-MM.
meta_description	`string` nullable	Short description from the outlet's meta tags.

Plus a standard meta object with credits_charged and credits_remaining.

Responses

200 OK

Show example response

json

{
    "data": [
        {
            "domain": "string",
            "affinity": 0,
            "visits": 0,
            "moz_da": 0,
            "moz_links": 0,
            "history": [],
            "meta_description": "string"
        }
    ],
    "meta": {
        "credits_charged": 0,
        "credits_remaining": 0,
        "credits_expires_at": "2026-01-01T00:00:00Z",
        "low_balance": true
    }
}

GET /v3/apps/{app_type} # 2 credits

Apps the audience uses

Parameters

Name	In	Type	Required	Description
app_type	path	string	required	Options: `ai`, `productivity`, `entertainment`, `lifestyle`, `finance`, `sports`, `ecommerce`
report_id	query	string	required	Report identifier returned by POST /v3/describe/create.
limit	query	integer	optional	Cap on the number of items returned. Narrows the response but never exceeds the endpoint's default cap.Default: `300`Range: min 1, max 300
history	query	string	optional	When `false`, the per-item `history` map is omitted from the response. Default `true`. When included, history is always trimmed to the most recent 12 months.Options: `true`, `false`Default: `true`

Example request

curl

curl -X GET "https://api.sparktoro.com/v3/apps/{app_type}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -G --data-urlencode "report_id=YOUR_REPORT_ID"

Response item fields

Field	Type	Description
domain	`string`	The app/service domain (e.g. gartner.com).
meta_description	`string` nullable	Short description from the domain's meta tags.
visits	`integer`	Estimated total monthly panel visits to this domain.
current_rank	`integer`	Rank within this audience for the requested category.
affinity	`number`	This audience's usage of the domain (0-100).
country_average	`number`	Country-baseline usage of the domain (0-100).
affinity_lift	`number`	How much the audience over/under-indexes the baseline (affinity − country_average), rounded to 2 decimals.
popular	`boolean`	True when this is a popular/mainstream pick within the category (not present on every item).
search_share	`number`	Present on /v3/apps/ai only. Google's search-engine market share fraction for this AI-category domain.

Plus a standard meta object with credits_charged and credits_remaining.

Responses

200 OK

Show example response

json

{
    "data": [
        {
            "domain": "string",
            "meta_description": "string",
            "visits": 0,
            "current_rank": 0,
            "affinity": 0,
            "country_average": 0,
            "affinity_lift": 0,
            "popular": true,
            "search_share": 0
        }
    ],
    "meta": {
        "credits_charged": 0,
        "credits_remaining": 0,
        "credits_expires_at": "2026-01-01T00:00:00Z",
        "low_balance": true
    }
}

Topics & intent

GET /v3/keywords # 5 credits

Search keywords

Parameters

Name	In	Type	Required	Description
report_id	query	string	required	Report identifier returned by POST /v3/describe/create.
limit	query	integer	optional	Cap on the number of items returned. Narrows the response but never exceeds the endpoint's default cap.Default: `300`Range: min 1, max 300
history	query	string	optional	When `false`, the per-item `history` map is omitted from the response. Default `true`. When included, history is always trimmed to the most recent 12 months.Options: `true`, `false`Default: `true`

Example request

curl

curl -X GET "https://api.sparktoro.com/v3/keywords" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -G --data-urlencode "report_id=YOUR_REPORT_ID"

Response item fields

Field	Type	Description
keyword	`string`	The search term.
affinity	`number`	This audience's affinity for the term (0-100).
volume	`integer`	Monthly Google search volume.
cpc	`number`	Estimated cost-per-click in USD.
competition	`number`	0-1 from Google Ads.
history	`object`	Monthly trend object keyed by YYYY-MM.

Plus a standard meta object with credits_charged and credits_remaining.

Responses

200 OK

Show example response

json

{
    "data": [
        {
            "keyword": "string",
            "affinity": 0,
            "volume": 0,
            "cpc": 0,
            "competition": 0,
            "history": []
        }
    ],
    "meta": {
        "credits_charged": 0,
        "credits_remaining": 0,
        "credits_expires_at": "2026-01-01T00:00:00Z",
        "low_balance": true
    }
}

GET /v3/prompts # 2 credits

AI prompt ideas

Parameters

Name	In	Type	Required	Description
report_id	query	string	required	Report identifier returned by POST /v3/describe/create.
limit	query	integer	optional	Cap on the number of items returned. Narrows the response but never exceeds the endpoint's default cap.Default: `300`Range: min 1, max 300

Example request

curl

curl -X GET "https://api.sparktoro.com/v3/prompts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -G --data-urlencode "report_id=YOUR_REPORT_ID"

Response item fields

Field	Type	Description
topic	`string`	AI prompt topic this audience is likely to ask about.
affinity	`number`	This audience's affinity for the prompt topic (0-100).

Plus a standard meta object with credits_charged and credits_remaining.

Responses

200 OK

Show example response

json

{
    "data": [
        {
            "topic": "string",
            "affinity": 0
        }
    ],
    "meta": {
        "credits_charged": 0,
        "credits_remaining": 0,
        "credits_expires_at": "2026-01-01T00:00:00Z",
        "low_balance": true
    }
}

Show example response

json

{
    "error": true,
    "status": 0,
    "message": "string"
}

Market size

GET /v3/tam # 3 credits

Total addressable market

Estimated total addressable market for the audience: population, year-over-year growth, annual market value, and the rationale (sources + assumptions) behind the estimate. Figures are model estimates, not exact counts. Cached per report after the first call.

Parameters

Name	In	Type	Required	Description
report_id	query	string	required	Report identifier returned by POST /v3/describe/create.

Example request

curl

curl -X GET "https://api.sparktoro.com/v3/tam" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -G --data-urlencode "report_id=YOUR_REPORT_ID"

Response fields

Field	Type	Description
data	`object`	Total addressable market estimate for the audience. All figures are model estimates, not exact counts — always surface the rationale to end users.

Plus a standard meta object with credits_charged and credits_remaining.

Responses

200 OK

Show example response

json

{
    "data": {
        "estimated_population": 0,
        "year_over_year_growth_pct": 0,
        "estimated_market_value": 0,
        "currency": "string",
        "rationale": "string"
    },
    "meta": {
        "credits_charged": 0,
        "credits_remaining": 0,
        "credits_expires_at": "2026-01-01T00:00:00Z",
        "low_balance": true
    }
}

06Sections that warm up

Creating a report is synchronous. POST /v3/describe/create returns 200 with "status": "ready" once the report is fully built — typically 10–20 seconds. There is no queue and no processing state to wait on: the moment you have a report_id, every section endpoint is callable.

Three sections are built from data collected by other sections of the report rather than queried directly — /v3/reddit, /v3/brands and /v3/prompts. If that data hasn't been collected yet, the request returns 202 and starts collecting it in the background.

202 Accepted

{
  "error": true,
  "status": 202,
  "message": "Report data is being prepared. Retry this request in a few seconds."
}

Retry the same request until it returns 200; collection usually finishes in under a minute. Retries are free — only the first request for a given section on a given report is charged, so polling costs no extra credits. Retries do still count against your rate limit, so honour the Retry-After header rather than polling tightly.

Every other section builds on demand and never returns 202.

07Errors

All errors return a JSON envelope with an error flag, HTTP status, and a human-readable message. Where useful, additional fields like credits_required, credits_remaining, limit_per_min, or retry_after are included.

Common statuses

Status	Meaning
202	Section not built yet. The request started the build — retry in a few seconds. Includes `Retry-After` (seconds). Only `/v3/reddit`, `/v3/brands`, and `/v3/prompts` return this. See Sections that warm up.
401	Missing or invalid API key.
402	Insufficient credits for this request. No charge applied. Includes `credits_required` and `credits_remaining`.
404	Endpoint or resource not found.
429	Rate limit exceeded. Includes `Retry-After` header (seconds).
500	Server error. The request is automatically refunded; safe to retry.

401 example

401 Unauthorized

{
  "error": true,
  "status": 401,
  "message": "Missing or invalid API key."
}

402 example

402 Insufficient Credits

{
  "error": true,
  "status": 402,
  "message": "Insufficient credits",
  "credits_required": 5,
  "credits_remaining": 2,
  "credits_expires_at": "2027-05-01T00:00:00Z"
}

429 example

429 Too Many Requests

{
  "error": true,
  "status": 429,
  "message": "Rate limit exceeded (60 req/min on your account).",
  "limit_per_min": 60,
  "retry_after": 18
}

Ready to build?

Grab an API key from your dashboard and start with the credits endpoint.

Go to dashboard →

SparkToro Public API

01Getting started

Your first call

02Authentication

Where to get a key

03Credits & metering

How credits are debited

Checking your balance

04Rate limits

05Endpoints

Example request

Response fields

Responses

Parameters

Example request

Response fields

Responses

Request body

Example request

Response fields

Responses

Parameters

Example request

Response fields

Responses

Parameters

Example request

Response item fields

Responses

Parameters

Example request

Response item fields

Responses

Parameters

Example request

Response item fields

Responses

Parameters

Example request

Response item fields

Responses

Parameters

Example request

Response item fields

Responses

Parameters

Example request

Response item fields

Responses

Parameters

Example request

Response item fields

Responses

Parameters

Example request

Response item fields

Responses

Parameters

Example request

Response item fields

Responses

Parameters

Example request

Response item fields

Responses

Parameters

Example request

Response item fields

Responses

Parameters

Example request

Response item fields

Responses

Parameters

Example request

Response fields

Responses

06Sections that warm up

07Errors

Common statuses