Core Concepts

Request ID

Every report submission returns a request_id (format: req_…). Use it to poll for the report status. Request IDs are unique per submission and scoped to your account.

Report state machine

A report moves through these states:

• queued — accepted, orchestration is starting.
• generating_questionnaire — the question and options are analyzed, audience filters are designed, and the questionnaire is generated.
• sampling — synthetic respondents are sampled and answer the questionnaire. This is usually the longest stage.
• completed — the report is ready. The response embeds the full result.
• failed — something went wrong. The response includes an error object with a message.

queued
  └─> generating_questionnaire
        └─> sampling
              ├─> completed
              └─> failed

Polling

Because the pipeline takes minutes, the API is async. Poll GET /api/v1/reports/{request_id}:

• Poll every 5 seconds while status is generating_questionnaire.
• Slow down to every 15 seconds once status is sampling — sampling is the longest stage.
• Stop polling when status is completed or failed.

Credits

Each sampled respondent costs exactly one credit.

• sample_size must be between 50 and 1000, and defaults to 100.
• Your balance is checked when you submit. If you have fewer credits than the requested sample size, the request is rejected with 402.
• Credits are reserved when sampling starts and consumed per successful respondent. Unused reserved credits are released back.
• The exact usage is returned as credits_used in the completed result, together with your remaining credits_left.

Reports are public

Completed reports get a public URL (report_url) that anyone with the link can view. The report page is shareable and indexable, similar to a published blog post. The raw analysis and sample_data JSON are also returned directly in the API response.

Language

Reports are generated in English by default. Pass language as en, es, or zh to choose explicitly.