gather

DOCS / QUICKSTART

A question in.
A research report out.

Start a simulated research report with one call. Get an ID immediately, then poll for the report and structured findings.

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.

POST /api/v1/reports
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.

FieldRequiredMeaning
companyYesCompany name, 2 to 120 characters.
questionYesThe decision to research, 10 to 600 characters.
websiteNoThe company website.
audienceNoWho to understand, 10 to 1,200 characters when supplied.
audience_typeNo"b2b" or "b2c".
key_questionsNoUp to 6 focused questions, each 10 to 300 characters.
respondentsNoInteger 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.

GET /api/v1/reports/{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.

StatusWhat your agent should do
queuedWait. Check again in 30 to 60 seconds.
runningKeep polling every 30 to 60 seconds.
completedStop polling. Read the report and structured output.
failedStop 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, and validation_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.

Optional request header
Idempotency-Key: acme-messaging-2026-01

Each key can have 3 reports running at once and has a daily limit. Daily limits reset at 00:00 UTC.

Handle errors clearly.

HTTP statusMeaningNext step
400Invalid input.Check field names, types, and lengths. Unknown fields are rejected.
401Invalid or revoked key.Check the key and authentication header.
403Workspace authorization failed.Ask Gather to check the key’s workspace access.
404Report not found for this key.Use the report ID and the same key that started it.
409Idempotency 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 / 415Request body too large or wrong content type.Send a supported JSON body with Content-Type: application/json.
429Concurrent, daily, or service limit reached.Wait before retrying. Daily key limits reset at 00:00 UTC.
503Service 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.

What would you ask
your buyers?

Start with the question that matters to your business.