Price a study before running it
estimate_studyAsk what a study would cost, without running it. Free.
Takes exactly the study fields run_study takes (kind, audience_ids, question, the kind's
material, respondents); read run_study for which material each kind needs. Returns the credits,
the rule behind the number, the wallet balance, what today's agent budget still allows,
default_respondents, max_respondents_under_cap (the largest panel today's remaining budget
covers for this kind) and confirm_recommended (true when a person should say yes before this
is spent). Do not submit when sufficient is false or blocked is set: the server will refuse
it. Audiences the workspace cannot use come back under rejected with a reason; run_study
refuses a submission that still names them. Pricing does not upload images or confirm that an
upload was received.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | url_feedback only: the page | |
| days | No | society only: simulated days (default 5) | |
| kind | Yes | closed_question | open_question | preference_test | image_reaction | url_feedback | survey | guide | focus_group | society | |
| events | No | society only: later facts placed on the timeline, each {day, text} | |
| topics | No | focus_group only: 1-12 discussion topics in order | |
| options | No | closed_question / preference_test: the answer options exactly as respondents read them | |
| platform | No | society only: weibo | xiaohongshu | x | reddit | internal (default: a generic feed) | |
| question | No | The exact question respondents receive, in the user's language. For focus_group/survey/guide: a one-line label | |
| stimulus | No | society only: the announcement, policy or message people react to, verbatim | |
| variants | No | society only: up to 4 other versions of the announcement, verbatim; the result ranks every version by how it moves opinion against saying nothing | |
| questions | No | survey / guide only, instead of instrument_id: the user's questions in order, each {question, options?, multi_select?}; leave options out for an open question | |
| image_refs | No | image_reaction only: refs from request_upload, once the image has been sent | |
| image_urls | No | image_reaction only: 1-3 public image URLs | |
| image_files | No | image_reaction only: host-provided chat attachments; prefer these over another upload. Never invent download_url or file_id | |
| respondents | No | Respondents per audience | |
| audience_ids | Yes | Audience ids from list_audiences (1-8) | |
| instrument_id | No | survey / guide only: the saved instrument's id | |
| material_is_description | No | true when respondents will see YOUR description of the user's material rather than the material itself; results are labelled accordingly | |
| respondents_by_audience | No | Per-audience override {audience_id: n} |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ok | No | false means the call failed: read `error` and `hint` | |
| hint | No | What to change, when ok is false | |
| kind | No | ||
| next | No | What to do next | |
| note | No | Something to tell the user or keep in mind | |
| rule | No | The pricing rule behind `credits` | |
| error | No | Error code, when ok is false | |
| balance | No | The workspace's credit balance | |
| blocked | No | The rail that refuses it, when any | |
| credits | No | What run_study would spend | |
| rejected | No | Audiences the workspace cannot use, each with a reason | |
| sufficient | No | Whether run_study would accept this study as priced | |
| respondents | No | Respondents per audience name | |
| workspace_budget | No | ||
| estimated_minutes | No | ||
| respondents_total | No | ||
| confirm_recommended | No | true: a person should say yes before this is spent | |
| default_respondents | No | The panel size used when `respondents` is omitted | |
| credits_per_respondent | No | ||
| max_respondents_under_cap | No | Largest panel per audience today's remaining budget covers |