1. Get a key.
Sign up with an email code: POST https://synthetic.gatherhq.com/api/v1/signup with your work email, then POST https://synthetic.gatherhq.com/api/v1/signup/verify with the code. It returns an agent key for your workspace, and creates the workspace when your company has none. Workspace admins can also create keys in Gather under Settings > API keys.
Store the key as GATHER_API_KEY in your server environment. Keep the key out of client-side code and public repositories.
Authenticate with Authorization: Bearer <key> or x-api-key: <key>. Send JSON with Content-Type: application/json. Use the same key to start, list, and check your reports.
2. Start a report.
curl https://synthetic.gatherhq.com/api/v1/reports \
-H "Authorization: Bearer $GATHER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"company":"Acme","question":"Which message do our buyers care about most, and what would make them switch?","audience":"IT leaders at mid-market US companies","audience_type":"b2b"}'One call researches the company, designs the interview guide, and runs 30 simulated interviews with your audience on Gather’s research platform in your own workspace. Choose 10 to 50 interviews when needed.
| Field | Required | Meaning |
|---|---|---|
company | Yes | Company name, 2 to 120 characters. |
question | Yes | The decision to research, 10 to 600 characters. |
website | No | The company website. |
audience | No | Who to understand, 10 to 1,200 characters when supplied. |
audience_type | No | "b2b" or "b2c". |
key_questions | No | Up to 6 focused questions, each 10 to 300 characters. |
respondents | No | Integer from 10 to 50. Default: 30 simulated interviews. |
Unknown fields are rejected. The default is 30 simulated interviews.
3. Keep the ID. Poll for completion.
The initial response is HTTP 202 and includes id, status, stage, and a relative poll_url. Save the returned id as REPORT_ID.
curl "https://synthetic.gatherhq.com/api/v1/reports/$REPORT_ID" \
-H "Authorization: Bearer $GATHER_API_KEY"Reports take about 16 minutes, or about 10 with 10 interviews. Poll every 30 to 60 seconds. Stop at either terminal status: completed or failed.
| Status | What your agent should do |
|---|---|
queued | Wait. Check again in 30 to 60 seconds. |
running | Keep polling every 30 to 60 seconds. |
completed | Stop polling. Read the report and structured output. |
failed | Stop polling. Read error.code and error.message. |
4. Put the findings to work.
A completed response includes:
report_url: the branded report link.output:headline,summary,answer,key_findings,options,priorities,points,next_steps,themes,quotes,unknowns, andvalidation_test.study.app_url: the study in your Gather workspace.methodology: how to interpret the report.confidence:"directional".
Results are simulated and directional. They are not a survey of real people.
Use GET /api/v1/reports to list this key’s reports, newest first. Add ?limit=10 to choose the page size. Supported values are 1 to 25.
5. Retry safely. Respect the limits.
Add an optional Idempotency-Key header before the first start request. Reuse that value and the same request body if the response is interrupted. An idempotent retry returns the existing report with HTTP 200, so it never starts a second report.
Use 8 to 100 letters, digits, or _ . : -. Reusing the value with different input returns 409.
Idempotency-Key: acme-messaging-2026-01Each key can have 3 reports running at once and has a daily limit. Daily limits reset at 00:00 UTC.
Handle errors clearly.
| HTTP status | Meaning | Next step |
|---|---|---|
400 | Invalid input. | Check field names, types, and lengths. Unknown fields are rejected. |
401 | Invalid or revoked key. | Check the key and authentication header. |
403 | Workspace authorization failed. | Ask Gather to check the key’s workspace access. |
404 | Report not found for this key. | Use the report ID and the same key that started it. |
409 | Idempotency conflict or report still being created. | Keep the same key and payload for a retry. Change the idempotency key only for a new report. |
413 / 415 | Request body too large or wrong content type. | Send a supported JSON body with Content-Type: application/json. |
429 | Concurrent, daily, or service limit reached. | Wait before retrying. Daily key limits reset at 00:00 UTC. |
503 | Service temporarily unavailable. | Retry later with the same idempotency key. |
If a report reaches failed, read error.code and error.message rather than continuing to poll.