Create a Grounded Audience from a Brief
create_audience_from_briefIdempotent
Creates a grounded Audience of synthetic Minds from a population or audience brief. It can combine authoritative web research, supplied sources, research files, and reviewed spreadsheet distributions; persists provenance and allocation audits; supports balanced, segment-coverage, and benchmark-depth sizing; can individually train every member of a large reviewed-dataset cohort in the background (trainMembers); is idempotent for identical inputs; and keeps the Audience private unless link sharing is enabled.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Optional Audience name override. When omitted, the server names the Audience from the brief or the LLM detection result. | |
| text | No | Legacy alias for `brief`. Accepted for back-compat. | |
| brief | No | Free-text brief describing the population the Audience should represent. E.g. "California high school students grades 9-12", "Berlin Späti customers", "Spanish lawyers", "management team of Coca Cola". The server runs deep web research on this brief to find demographic / psychographic distributions from authoritative sources, then generates personas that proportionally reflect those distributions. | |
| files | No | Optional already-uploaded research files. MCP cannot read or upload a local file:// path. Use a fetchable HTTP(S) URL, a signed URL supplied by the client for the attached file, or an existing Minds workspace upload URL/path. Study tools import external file URLs into durable Minds storage before saving or running. The Study refuses to start if Minds cannot read the asset. The server analyzes these through the same extended screener/questionnaire path as the in-app New Audience uploader, including study roles, screening and quota rules, review distributions, and grounding provenance. | |
| links | No | Optional URLs scraped server-side for additional context (e.g. an article describing the population). | |
| keywords | No | Optional Exa web-search seeds added alongside the brief. | |
| memberCount | No | Exact number of Minds to create in the Audience. Pass this whenever the user states a size ("exactly 50 per region", "genau 50 Minds je Zelle") instead of relying on the server to parse the number out of the brief prose. When omitted, the size is inferred from the brief and, failing that, from the creation mode's evidence-based automatic sizing. Rejected with 403 PLAN_LIMIT when it exceeds the plan's per-Audience cap; the Audience is never created at a partial size. | |
| trainMembers | No | Opt-in per-Mind training for large reviewed-dataset cohorts (default false). By default a reviewed-dataset Audience of more than ~40 Minds is bulk-created immediately ready: exact demographics, but no per-Mind research training (empty system prompt, no knowledge items). Set true to create those Minds untrained instead and enqueue each one through the same per-member training pipeline the in-app draft flow uses, preserving its deterministic cohort profile and the request locale. The tool still returns as soon as the Audience exists — training continues in the background (structuredContent.audience.memberTraining reports what was queued); poll each member with GET /api/v1/minds/{id}/training. Has no effect on Audiences whose members are already trained individually. | |
| cohortAllocation | No | Deterministic allocation controls. Reviewed respondent datasets default to observed, which preserves the strongest privacy-safe structural relationships while keeping exact marginals; other sources default to independence. Use distributionNames/maxDistributions to choose axes, minSegmentCount for a feasible floor, and seed for reproducible external runs. | |
| includeWebSearch | No | Set false to skip Exa web search and extraction completely. The Audience is then grounded only on the brief and supplied files, links, keywords, and structurally parsed respondent data. | |
| groupCreationMode | No | Audience creation mode. "balanced" (default): compact, representative Audience for everyday research. "segment_coverage": two representatives per limiting grounded audience cell, with a 10-Mind evidence floor and 50-Mind mode ceiling. "benchmark_depth": repeated representation of limiting grounded audience cells for validation-ready benchmark / survey-style segmentation, with the paid allowance as its ceiling. The deeper modes require a Team (enterprise) plan — on other plans the server SILENTLY downgrades to "balanced" and echoes the effective mode in the response (structuredContent.audience.audienceCreationMode). This field is the legacy alias for audienceCreationMode. | |
| datasetSegmentation | No | Reviewed variable roles, distributions, and privacy-safe pairwise relationships returned by preview_audience_dataset_segmentation. Requires audienceCreationMode="benchmark_depth". Structural variables shape one generalizable representative cohort; outcomes remain held out and joint combinations remain audit evidence only. Copy `respondentCount` and `recommendedMindCount` through from the preview — they cap the cohort size. | |
| audienceCreationMode | No | Audience creation mode. Preferred. Use balanced for everyday research, segment_coverage for coverage of limiting grounded cells, or benchmark_depth for validation-ready repeated representation. | |
| isLinkSharingEnabled | No | Set true ONLY when the user explicitly asked for a public/shareable link. Defaults to false: the Audience is private to its owner and no share URL is generated. Enabling this publishes the Audience — including its grounding, sources and personas — at a world-readable URL that needs no login. Do not enable it to "be helpful". |