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

{
  "plan_id": 9,
  "plan_name": "api_starter",
  "period_start": "2026-05-01 00:00:00",
  "period_end": "2026-05-31 23:59:59",
  "credits_total": 4000,
  "credits_used": 0,
  "credits_remaining": 4000
}

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. Limits scale with your plan:

Plan	Limit
Free	10 requests / minute
Starter	30 requests / minute
Growth	60 requests / minute
Agency	120 requests / minute

Hitting the limit returns 429 Too Many Requests with a Retry-After header (seconds until the next minute bucket).

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
}

Audience reports

POST /v3/describe/create # 10 credits

Create an audience report

Costs 10 credits. Kicks off asynchronous report generation. Returns a `report_id` you pass to the section endpoints.

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`	Report state. Sections can be queried once status is 'ready'.Options: `processing`, `ready`, `error`
message	`string`	Human-readable confirmation or error detail.

Responses

202 Report queued. Poll the section endpoints (or report status) until data is available.

Show example response

json

{
    "report_id": "string",
    "status": "processing",
    "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).
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",
            "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/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	`integer`	SparkToro's internal numeric channel id.
channel_id	`string`	YouTube's own channel id.
channel_url	`string (uri)`	Canonical YouTube channel URL.
title	`string`	Channel name.
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": 0,
            "channel_id": "string",
            "channel_url": "https://example.com",
            "title": "string",
            "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
title	`string`	Show title.
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": [
        {
            "title": "string",
            "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
    }
}

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
    }
}

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
    }
}

06Errors

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
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,
  "period_end": "2026-05-31 23:59:59"
}

429 example

429 Too Many Requests

{
  "error": true,
  "status": 429,
  "message": "Rate limit exceeded (30 req/min on your plan).",
  "limit_per_min": 30,
  "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

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 fields

Responses

06Errors

Common statuses

401 example

402 example

429 example

Ready to build?

Keep up with SparkToro®

Keep up with SparkToro^®