Probably
Start free
Docs

Prepare audience research

prepare_audience_research, in Changes: A connection or key that may make changes. None spends credits; prepare_* and stage tools (research, brainstorm, write_script, review, generate_clip, voice, storyboard) prepare paid work for confirm_spend.

POST
/api/v1/tools/prepare_audience_research

Prepare research into who buys one of a Space's products: public remarks from Reddit, TikTok, Amazon, Trustpilot and TikTok Shop are collected, labelled by awareness, and sorted into segments, which it saves when it finishes. It runs on the Space, not a video. The preview's ceilingCredits is the most it can charge, which confirming reserves whole, and its estimatedCredits what a run usually costs: research is charged what it costs, past the ceiling Probably pays, and what it doesn't spend is released when it ends. Nothing is spent until it is confirmed; follow it with get_audience_research. Show the person the preview. If the connection may spend, call confirm_spend with the confirmationId once they agree; otherwise send them the confirmUrl to confirm it in the studio. It expires in 15 minutes. Pass a new requestKey; repeating one returns the same confirmation.

Authorization

apiKey
headerAuthorizationBearer <token>

An API key (prb_…) from Settings → Connections.

Request Body

application/json
  1. body
spaceId*string
Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid
productRecordId*string

The Space's product whose buyers to research (list_products)

Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid
site?string

The brand's site, like javycoffee.com: remarks that name it count as naming the brand

Lengthlength <= 200
competitors?array<>
Itemsitems <= 8
Default[]
requestKey*string
Match^[\w.:-]+$
Length8 <= length <= 64

Response Body

The tool's answer.

application/json
  1. response
spaceId*string
Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid
confirmationId*string
Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid
expiresAt*string
preview*||||||
confirmUrl*|null
curl -X POST 'https://studio.probably.co/api/v1/tools/prepare_audience_research' \  -H "Authorization: Bearer $PROBABLY_API_KEY" \  -H 'Content-Type: application/json' \  -d '{  "spaceId": "5b0e7c1a-3f52-4d8e-9a61-2c4f8e9d7b30",  "productRecordId": "0d1e2f3a-4b5c-4d6e-8f70-81920a3b4c5d",  "site": "javycoffee.com",  "competitors": [    "Jot",    "Chamberlain"  ],  "requestKey": "research-javy-1"}'
{  "spaceId": "5b0e7c1a-3f52-4d8e-9a61-2c4f8e9d7b30",  "confirmationId": "e7a1b2c3-d4e5-4f60-8172-93a4b5c6d7e8",  "expiresAt": "2026-10-27T09:15:00.000Z",  "preview": {    "kind": "audience-research",    "ceilingCredits": 2000,    "estimatedCredits": 1640,    "availableCredits": 2840,    "fits": true,    "sandbox": false  },  "confirmUrl": null}