Passer au contenu principal
POST

Autorisations

Authorization
string
header
requis

Your API key, sent as Authorization: Bearer <key>.

Corps

application/json
seed
string
requis

The topic: letters, digits and single spaces, such as sunscreen. A short product or category term works best; a sentence finds nothing.

Required string length: 1 - 30
country
enum<string>
requis

Market: KR (South Korea) or US (United States). Any other value is a 422 REGION_UNSUPPORTED.

Options disponibles:
KR,
US
limit
integer
défaut:20

Prompts to return, at least depth + 1.

Plage requise: 1 <= x <= 100
depth
integer
défaut:2

The most conditions one prompt combines. Every depth from 0 up to it is returned: 0 is each product kind's plain ask, 1 adds one condition (a budget, an answer to one of the kind's questions, a searched variant), and 2 and 3 combine conditions from different questions.

Plage requise: 0 <= x <= 3
cores
string[]

Product kinds to research in place of the ones the research picks, with the seed's rules. Spellings that differ only in case or spacing count once.

Required array length: 1 - 5 elements
Required string length: 1 - 30
exclude
string[]

Terms to leave out, such as a subtopic you do not want. A prompt containing one is left out. Put your own brand in brand.

Maximum array length: 20
Required string length: 1 - 30
brand
string

Your brand, with at least two letters or digits; punctuation is allowed. Prompts containing it are left out, as with exclude.

Required string length: 1 - 80
brandAliases
string[]

Other names or spellings of your brand, left out the same way. Requires brand.

Maximum array length: 10
Required string length: 1 - 80
brandDescription
string

What your brand sells and to whom. Requires brand. Adds fit to every prompt, favors the prompts your brand answers and leaves out the ones it rules out.

Maximum string length: 500
idempotencyKey
string

Optional. Deduplicates submissions for at least 30 days after the request; a duplicate is a 409.

priority
integer
défaut:1

Optional. Echoed in task metadata; values outside 1-10 are clamped. It does not guarantee execution order.

Plage requise: 1 <= x <= 10
webhook
object

Optional. Omit to collect the result by polling instead.

Réponse

Queued; poll /v1/async/task/{id}. Its response follows PromptResearchResult.

success
boolean
requis
task
object
requis
credits
object
requis

Credits, with up to two decimals (for example 1.25). The submit response always shows 0: nothing is charged yet, and the task's price is held from your balance when it starts. Polling shows 0 until the task is terminal, then the settled charge: the task's price for COMPLETED, 0 for FAILED. A task webhook reports the same charge in creditsCharged; on a FAILED task it reports the task's price in creditsToCharge and 0 in creditsCharged. CITATION_ANALYSIS, GOOGLE_PLACES and GOOGLE_NEWS are charged by usage, up to the hold placed when the task starts.