Create a Research run

The question that gives the investigation its direction and keeps each source artifact tied to the caller's goal. Keep it between 1 and 20,000 characters so the request remains focused and bounded.

Selects the request shape the service should interpret. Use version 2 when sending reference_artifact_ids, because explicit prior-artifact context is supported only by that contract version.

Default: 2

Chooses a preset level of source coverage and discovery effort for the run. Use it when a simple capacity choice is more useful than setting each target separately; the supported values map to 15, 50, or 100 sources.

Sets how many sources the investigation should try to examine. The value can be from 1 through 1,000, keeping the requested scope visible and bounded before work starts.

Sets how many discovery searches the run must make while looking for useful material, from 1 through 100. When searches come back empty the run may make up to 4 more, never more than 100 in all, and its wallet hold covers that maximum.

Chooses whether the investigation searches scholarly papers, general web resources, or both. At least one and no more than two implemented values may be supplied, and the default includes both surfaces.

Default: ["paper", "web"]

Suggests reviewed source sites that should influence discovery. These are soft preferences, so unknown site values may be ignored rather than preventing the rest of the run from completing.

Limits discovery to the listed hosts, and every host must be one of these 39 reviewed scholarly sites: arxiv.org, biorxiv.org, medrxiv.org, ssrn.com, osf.io, zenodo.org, semanticscholar.org, openreview.net, openalex.org, core.ac.uk, doaj.org, dblp.org, paperswithcode.com, aclanthology.org, proceedings.mlr.press, neurips.cc, huggingface.co, pubmed.ncbi.nlm.nih.gov, europepmc.org, nature.com, science.org, sciencedirect.com, link.springer.com, onlinelibrary.wiley.com, ieeexplore.ieee.org, dl.acm.org, jstor.org, plos.org, pnas.org, cell.com, thelancet.com, nejm.org, bmj.com, frontiersin.org, mdpi.com, tandfonline.com, journals.sagepub.com, cambridge.org, academic.oup.com. Any other host returns 422. You may provide up to 50 hostname-only values, and none may also appear in exclude_domains.

Keeps the listed hostnames out of discovery; unlike include_domains, any hostname is accepted. You may provide up to 50 hostname-only values, and none may overlap include_domains because a domain cannot be both required and excluded.

Favors material published after the supplied calendar date. The value must be a real date in YYYY-MM-DD format so the filter has an unambiguous meaning.

Tells discovery which language should be preferred when selecting material. Values must be between 2 and 12 characters, and the default is en.

Default: en

Limits what the run is charged, including the 5-cent run fee and 25% margin: the run stops before the next provider or model operation that would pass the cap, and the fee and margin never take the run past it. The value can be from 25 through 2,500 cents and defaults to 500 or your saved setting; a cap below what discovery must hold before it starts is refused, and the error names the minimum.

Accepted as up to 20 reference names and stored with the run's request, but the current service never reads them, so they change nothing about the run. Never place raw provider credentials in a request.

Adds a deliberate set of previously saved artifacts as context for the next investigation, when appending to a thread. Supply up to 15 unique encrypted public tokens and use request schema version 2; the service does not load every old artifact automatically. Create refuses any value with 422, because a new thread has no saved artifacts.