Studies

Returns data of studies matching query and filter parameters. The studies are returned page by page. If response contains `nextPageToken`, use its value in `pageToken` to get next page. The last page will not contain `nextPageToken`. A page may have empty `studies` array. Request for each subsequent page must have the same parameters as for the first page, except `countTotal`, `pageSize`, and `pageToken` parameters. If neither queries nor filters are set, all studies will be returned. If any query parameter contains only NCT IDs (comma- and/or space-separated), filters are ignored. `query.*` parameters are in [Essie expression syntax](/find-studies/constructing-complex-search-queries). Those parameters affect ranking of studies, if sorted by relevance. See `sort` parameter for details. `filter.*` and `postFilter.*` parameters have same effect as there is no aggregation calculation. Both are available just to simplify applying parameters from search request. Both do not affect ranking of studies. Note: When trying JSON format in your browser, do not set too large `pageSize` parameter, if `fields` is unlimited. That may return too much data for the browser to parse and render.

byClinicalTrials.gov

4308calls

N/Alatency

Discover -> Inspect -> Call

Call setup

Tool IDclinicaltrials_gov.studies.retrieve.v1.92e933d8

Request parametersJSON

Before this Call

1 credit / call

The final charge is settled from actual provider usage and will appear in Usage.

Field reference

formatstringOptional

Must be one of the following: * `csv`- return CSV table with one page of study data; first page will contain header with column names; available fields are listed on [CSV Download](/data-api/about-api/csv-download) page * `json`- return JSON with one page of study data; every study object is placed in a separate line; `markup` type fields format depends on `markupFormat` parameter

markupFormatstringOptional

Format of `markup` type fields: * `markdown`- [markdown](https://spec.commonmark.org/0.28/) format * `legacy`- compatible with classic PRS Applicable only to `json` format.

query.condstringOptional

"Conditions or disease" query in [Essie expression syntax](/find-studies/constructing-complex-search-queries). See "ConditionSearch Area" on [Search Areas](/data-api/about-api/search-areas#ConditionSearch) for more details.

query.termstringOptional

"Other terms" query in [Essie expression syntax](/find-studies/constructing-complex-search-queries). See "BasicSearch Area" on [Search Areas](/data-api/about-api/search-areas#BasicSearch) for more details.

query.locnstringOptional

"Location terms" query in [Essie expression syntax](/find-studies/constructing-complex-search-queries). See "LocationSearch Area" on [Search Areas](/data-api/about-api/search-areas#LocationSearch) for more details.

query.titlesstringOptional

"Title / acronym" query in [Essie expression syntax](/find-studies/constructing-complex-search-queries). See "TitleSearch Area" on [Search Areas](/data-api/about-api/search-areas#TitleSearch) for more details.

query.intrstringOptional

"Intervention / treatment" query in [Essie expression syntax](/find-studies/constructing-complex-search-queries). See "InterventionSearch Area" on [Search Areas](/data-api/about-api/search-areas#InterventionSearch) for more details.

query.outcstringOptional

"Outcome measure" query in [Essie expression syntax](/find-studies/constructing-complex-search-queries). See "OutcomeSearch Area" on [Search Areas](/data-api/about-api/search-areas#OutcomeSearch) for more details.

query.sponsstringOptional

"Sponsor / collaborator" query in [Essie expression syntax](/find-studies/constructing-complex-search-queries). See "SponsorSearch Area" on [Search Areas](/data-api/about-api/search-areas#SponsorSearch) for more details.

query.leadstringOptional

Searches in "LeadSponsorName" field. See [Study Data Structure](/data-api/about-api/study-data-structure#LeadSponsorName) for more details. The query is in [Essie expression syntax](/find-studies/constructing-complex-search-queries).

query.idstringOptional

"Study IDs" query in [Essie expression syntax](/find-studies/constructing-complex-search-queries). See "IdSearch Area" on [Search Areas](/data-api/about-api/search-areas#IdSearch) for more details.

query.patientstringOptional

See "PatientSearch Area" on [Search Areas](/data-api/about-api/search-areas#PatientSearch) for more details.

filter.overallStatusarrayOptional

Filter by comma- or pipe-separated list of statuses

filter.geostringOptional

Filter by geo-function. Currently only distance function is supported. Format: `distance(latitude,longitude,distance)`

filter.idsarrayOptional

Filter by comma- or pipe-separated list of NCT IDs (a.k.a. ClinicalTrials.gov identifiers). The provided IDs will be searched in [NCTId](data-api/about-api/study-data-structure#NCTId) and [NCTIdAlias](data-api/about-api/study-data-structure#NCTIdAlias) fields.

filter.advancedstringOptional

Filter by query in [Essie expression syntax](/find-studies/constructing-complex-search-queries)

filter.synonymsarrayOptional

Filter by comma- or pipe-separated list of `area`:`synonym_id` pairs

postFilter.overallStatusarrayOptional

Filter by comma- or pipe-separated list of statuses

postFilter.geostringOptional

Filter by geo-function. Currently only distance function is supported. Format: `distance(latitude,longitude,distance)`

postFilter.idsarrayOptional

postFilter.advancedstringOptional

Filter by query in [Essie expression syntax](/find-studies/constructing-complex-search-queries)

postFilter.synonymsarrayOptional

Filter by comma- or pipe-separated list of `area`:`synonym_id` pairs

aggFiltersstringOptional

Apply aggregation filters, aggregation counts will not be provided. The value is comma- or pipe-separated list of pairs `filter_id`:`space-separated list of option keys` for the checked options.

geoDecaystringOptional

Set proximity factor by distance from `filter.geo` location to the closest [LocationGeoPoint](/data-api/about-api/study-data-structure#LocationGeoPoint) of a study. Ignored, if `filter.geo` parameter is not set or response contains more than 10,000 studies.

fieldsstringOptional

If specified, must be non-empty comma- or pipe-separated list of fields to return. If unspecified, all fields will be returned. Order of the fields does not matter. For `csv` format, specify list of columns. The column names are available on [CSV Download](/data-api/about-api/csv-download). For `json` format, every list item is either area name, piece name, field name, or special name. If a piece or a field is a branch node, all descendant fields will be included. All area names are available on [Search Areas](/data-api/about-api/search-areas), the piece and field names — on [Data Structure](/data-api/about-api/study-data-structure) and also can be retrieved at `/studies/metadata` endpoint. There is a special name, `@query`, which expands to all fields queried by search.

sortarrayOptional

Comma- or pipe-separated list of sorting options of the studies. The returning studies are not sorted by default for a performance reason. Every list item contains a field/piece name and an optional sort direction (`asc` for ascending or `desc` for descending) after colon character. All piece and field names can be found on [Data Structure](/data-api/about-api/study-data-structure) and also can be retrieved at `/studies/metadata` endpoint. Currently, only date and numeric fields are allowed for sorting. There is a special "field" `@relevance` to sort by relevance to a search query. Studies missing sort field are always last. Default sort direction: * Date field - `desc` * Numeric field - `asc` * `@relevance` - `desc`

countTotalbooleanOptional

Count total number of studies in all pages and return `totalCount` field with first page, if `true`. For CSV, the result can be found in `x-total-count` response header. The parameter is ignored for the subsequent pages.

pageSizeintegerOptional

Page size is maximum number of studies to return in response. It does not have to be the same for every page. If not specified or set to 0, the default value will be used. It will be coerced down to 1,000, if greater than that.

pageTokenstringOptional

Token to get next page. Set it to a `nextPageToken` value returned with the previous page in JSON format. For CSV, it can be found in `x-next-page-token` response header. Do not specify it for first page.

Studies

byClinicalTrials.gov

4308calls

N/Alatency