Run synthetic brand, messaging, competitive, and pricing research programmatically. Integrate AI-moderated research studies into any product or workflow.
https://synthetic.gatherhq.com/api/v1All API requests require a Bearer token in the Authorization header. Contact mayank@gatherhq.com to get an API key, or use your ADMIN_SECRET for internal Gather platform calls.
Authorization: Bearer your_api_key_here
/studiesRun a full synthetic research study. Returns structured findings when complete (30-90s).
| Name | Type | Required | Description |
|---|---|---|---|
topic | string | yes | Research question. Be specific — 10+ characters. |
study_type | string | yes | One of: brand, product, concept, competitor, cx, pricing, messaging, winloss, churn, segmentation, custom |
audience | string | yes | b2b or b2c — determines default persona selection |
persona_ids | string[] | no | Specific persona IDs to interview. Max 4. See GET /personas. |
n_per_persona | number | no | Interviews per persona. 1-3, default 2. Total = personas × n_per_persona. |
webhook_url | string | no | URL to POST study.completed event to when finished. |
{
"topic": "How do mid-market CFOs evaluate AI-powered FP&A tools?",
"study_type": "competitor",
"audience": "b2b",
"persona_ids": ["p_cfo", "p_cto"], // optional — defaults auto-selected
"n_per_persona": 2, // optional — 1-3, default 2
"webhook_url": "https://your.app/hook" // optional — POST on completion
}{
"id": "d80af9bb-797f-43d2-9cb3-8ac822c7d3e4",
"status": "complete",
"topic": "How do mid-market CFOs evaluate AI-powered FP&A tools?",
"study_type": "competitor",
"audience": "b2b",
"slug": "mid-market-cfos-ai-fpa-tools-competitive-analysis",
"report_url": "https://synthetic.gatherhq.com/report/d80af9bb-...",
"headline_finding": "CFOs trust vendors who lead with ROI proof...",
"executive_summary": "...",
"overall_confidence": 68,
"avg_sentiment": 6.2,
"key_findings": [
{
"finding": "...",
"evidence": "...",
"implication": "...",
"strength": "strong"
}
],
"opportunity": "...",
"risk": "...",
"messaging_implications": ["...", "..."],
"quant": { "projected_nps": 32, ... },
"created_at": "2026-03-25T14:30:00Z"
}/studiesList completed studies with pagination and filtering.
| Name | Type | Required | Description |
|---|---|---|---|
limit | number | no | Results per page. Default 20, max 100. |
offset | number | no | Pagination offset. Default 0. |
study_type | string | no | Filter by study type. |
audience | string | no | Filter by audience: b2b or b2c. |
{
"studies": [
{
"id": "d80af9bb-...",
"topic": "...",
"study_type": "brand",
"audience": "b2c",
"slug": "starbucks-brand-perception-brand-study",
"report_url": "https://synthetic.gatherhq.com/report/d80af9bb-...",
"headline_finding": "...",
"overall_confidence": 68,
"avg_sentiment": 6.5,
"created_at": "2026-03-25T14:30:00Z"
}
],
"total": 48,
"limit": 20,
"offset": 0
}/studies/:idRetrieve full study results including synthesis, quant data, and all interview transcripts.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Study UUID |
{
"id": "d80af9bb-...",
"status": "complete",
"topic": "...",
"headline_finding": "...",
"executive_summary": "...",
"key_findings": [...],
"consensus_themes": [...],
"opportunity": "...",
"risk": "...",
"competitive_signals": [...],
"decision_criteria": [...],
"messaging_implications": [...],
"research_agenda": [...],
"quant": { ... },
"interviews": [
{
"persona_id": "p_cfo",
"persona_name": "James L.",
"persona_role": "CFO",
"transcript": [
{ "q": "...", "a": "..." }
],
"analysis": {
"sentiment": "mixed",
"sentiment_score": 5.5,
"key_themes": [...],
"standout_quote": "...",
...
}
}
]
}/personasGet all available synthetic personas with demographics and traits.
{
"b2b": [
{
"id": "p_cmo",
"name": "Priya S.",
"age": 41,
"role": "CMO",
"company": "Enterprise Retail",
"industry": "Enterprise",
"income": "$240k",
"location": "New York, NY",
"traits": ["brand-conscious", "board pressure", "agency veteran"]
},
...
],
"b2c": [...],
"defaults": {
"b2b": ["p_cmo", "p_cto", "p_cfo", "p_vp_mktg"],
"b2c": ["p_millennial_mom", "p_gen_z", "p_high_income", "p_budget"]
}
}/study-typesGet all available study types with descriptions.
{
"study_types": [
{
"id": "brand",
"label": "Brand Perception",
"description": "How audiences perceive a brand — affinity, trust, associations.",
"default_audience": "b2c"
},
...
]
}All errors return a JSON body with error and message fields.
| Status | Error code | When |
|---|---|---|
400 | invalid_topic | topic is missing or under 10 characters |
400 | invalid_study_type | study_type is not a recognized value |
400 | invalid_audience | audience is not 'b2b' or 'b2c' |
400 | invalid_json | Request body is not valid JSON |
401 | unauthorized | Missing or malformed Authorization header |
403 | invalid_key | API key is not recognized |
404 | not_found | Study ID does not exist |
500 | research_failed | Study execution failed (timeout, model error) |
Pass a webhook_url when creating a study. We'll POST to it when the study completes:
{
"event": "study.completed",
"study_id": "d80af9bb-...",
"report_url": "https://synthetic.gatherhq.com/report/d80af9bb-...",
"topic": "...",
"study_type": "brand",
"audience": "b2c"
}Studies take 30-90 seconds to complete. The API is synchronous — the response includes the full results.
Pricing: B2C interviews $0.50 each, B2B interviews $5.00 each. Default study = 4 personas × 2 interviews = 8 interviews. A B2B study costs ~$40, a B2C study costs ~$4.
Rate limit: 10 concurrent studies per API key. Contact us for higher limits.
curl -X POST https://synthetic.gatherhq.com/api/v1/studies \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"topic": "How do consumers perceive Starbucks after recent controversies?",
"study_type": "brand",
"audience": "b2c"
}'const res = await fetch("https://synthetic.gatherhq.com/api/v1/studies", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
topic: "How do consumers perceive Starbucks after recent controversies?",
study_type: "brand",
audience: "b2c",
}),
});
const study = await res.json();
console.log(study.headline_finding);
console.log(study.report_url);import requests
res = requests.post(
"https://synthetic.gatherhq.com/api/v1/studies",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={
"topic": "How do consumers perceive Starbucks after recent controversies?",
"study_type": "brand",
"audience": "b2c",
},
)
study = res.json()
print(study["headline_finding"])
print(study["report_url"])Synthetic data: All research uses AI-generated synthetic respondents — not real humans. Findings are directional signal with ±15-20% margin of error. Treat as hypotheses to validate.
Brand independence: Studies mentioning brands are independent research, not affiliated with or endorsed by those brands.
Primary research: For real human respondents, use gatherhq.com.