Prolific studies API
The studies API from Prolific — 18 operation(s) for studies.
OpenAPI Specification
openapi: 3.1.0
info:
title: API Reference aiTaskBuilder studies API
version: 1.0.0
servers:
- url: https://api.prolific.com
description: Production
tags:
- name: studies
paths:
/api/v1/studies/:
get:
operationId: get-studies
summary: List all studies
description: List all studies, with the option to filter by study status.
tags:
- studies
parameters:
- name: state
in: query
description: Filter studies by status. Accepts a string in the format "(active|published|...)", where "active" and "published" are example statuses.
required: false
schema:
$ref: '#/components/schemas/ApiV1StudiesGetParametersState'
- name: Authorization
in: header
description: 'The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.
Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.
If your token is leaked, delete it and create a new one directly in the app.
In your requests add `Authorization` header with the value `Token <your token>`.'
required: true
schema:
type: string
responses:
'200':
description: List of studies
content:
application/json:
schema:
$ref: '#/components/schemas/StudiesListResponse'
'400':
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDetail'
post:
operationId: create-study
summary: Create a draft study
description: 'Create a draft study. Publishing a study is a two step process, first create a draft study then publish it.
## Taskflow Studies:
Taskflow studies are created in the same manner as regular studies, however instead of providing an **external_study_url**, you should
provide an access_details array with **access_detail** objects instead, containing an external_url field and a total_allocation field.'
tags:
- studies
parameters:
- name: Authorization
in: header
description: 'The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.
Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.
If your token is leaked, delete it and create a new one directly in the app.
In your requests add `Authorization` header with the value `Token <your token>`.'
required: true
schema:
type: string
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/Study'
'400':
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDetail'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateStudy'
/api/v1/projects/{project_id}/studies/:
get:
operationId: get-project-studies
summary: List all studies in a project
description: 'List all of your studies in a project.
For projects with a large number of studies, pagination can be used to optimize the response size and performance. To paginate, use the `page`, `page_size` and `ordering` query parameters. For example, to retrieve the first 10 studies, use `/api/v1/projects/{project_id}/studies/?page=1&page_size=10&ordering=-date_created`.'
tags:
- studies
parameters:
- name: project_id
in: path
description: Project id
required: true
schema:
type: string
- name: page
in: query
description: The page number to retrieve.
required: false
schema:
type: integer
- name: page_size
in: query
description: The number of studies to retrieve per page.
required: false
schema:
type: integer
- name: ordering
in: query
description: The ordering of the studies. Use `-date_created` to order by date created in descending order.
required: false
schema:
type: string
- name: Authorization
in: header
description: 'The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.
Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.
If your token is leaked, delete it and create a new one directly in the app.
In your requests add `Authorization` header with the value `Token <your token>`.'
required: true
schema:
type: string
responses:
'200':
description: List of studies for the given project
content:
application/json:
schema:
$ref: '#/components/schemas/StudiesListResponse'
'400':
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDetail'
/api/v1/projects/{project_id}/studies/{study_id}/:
delete:
operationId: delete-project-study
summary: Delete a study from a project
description: Delete a study and remove it from a project. Only draft studies can be deleted.
tags:
- studies
parameters:
- name: project_id
in: path
description: Project id
required: true
schema:
type: string
- name: study_id
in: path
description: Study id
required: true
schema:
type: string
- name: Authorization
in: header
description: 'The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.
Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.
If your token is leaked, delete it and create a new one directly in the app.
In your requests add `Authorization` header with the value `Token <your token>`.'
required: true
schema:
type: string
responses:
'204':
description: Deleted
content:
application/json:
schema:
type: object
properties: {}
'400':
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDetail'
/api/v1/studies/{id}/:
get:
operationId: get-study
summary: Retrieve a study
description: Retrieve a study by id. If you are polling the API for updates to a study, consider using a [Hook](#tag/Hooks). We will call your endpoint when certain events occur on your study, such as new completed submissions or changes in status.
tags:
- studies
parameters:
- name: id
in: path
description: Study id
required: true
schema:
type: string
- name: Authorization
in: header
description: 'The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.
Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.
If your token is leaked, delete it and create a new one directly in the app.
In your requests add `Authorization` header with the value `Token <your token>`.'
required: true
schema:
type: string
responses:
'200':
description: Found
content:
application/json:
schema:
$ref: '#/components/schemas/Study'
'400':
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
delete:
operationId: delete-study
summary: Delete a study
description: Published studies cannot be deleted, but you can delete draft studies.
tags:
- studies
parameters:
- name: id
in: path
description: Study id
required: true
schema:
type: string
- name: Authorization
in: header
description: 'The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.
Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.
If your token is leaked, delete it and create a new one directly in the app.
In your requests add `Authorization` header with the value `Token <your token>`.'
required: true
schema:
type: string
responses:
'200':
description: Deleted
content:
application/json:
schema:
$ref: '#/components/schemas/Studies_DeleteStudy_Response_200'
'400':
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
patch:
operationId: update-study
summary: Update a study
description: 'You can update any field for a draft study.
Once the study has been published only the following fields can be updated with some restrictions:
- internal_name: Internal name of the study, not shown to participants
- total_available_places: Only increasing is allowed. A completed study will become active again and resume recruiting of participants. For more information, check the [guide](https://researcher-help.prolific.com/en/articles/445201-how-do-i-increase-places-on-a-study)
- access_details: Sending an access_detail will add a new task and increase overall study places by the number in the total_allocation field. Sending both access_details and total_available_places will increase places on existing URLs by the number specified on the access_detail.
- data_collection_metadata.annotators_per_task: For AI Task Builder Batch studies, you can increase the number of annotators per task. This will automatically recalculate `total_available_places` based on the number of task groups multiplied by the new value. Note: This value can only be increased, not decreased, on a published study.
- submissions_config: This allows you to update the max_submissions_per_participant, max_concurrent_submissions, or auto_rejection_categories. Please note decreasing max_submissions_per_participant will not affect submissions that have already been created.'
tags:
- studies
parameters:
- name: id
in: path
description: Study id
required: true
schema:
type: string
- name: Authorization
in: header
description: 'The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.
Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.
If your token is leaked, delete it and create a new one directly in the app.
In your requests add `Authorization` header with the value `Token <your token>`.'
required: true
schema:
type: string
responses:
'200':
description: Updated
content:
application/json:
schema:
$ref: '#/components/schemas/Study'
'400':
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BaseStudy'
/api/v1/studies/{id}/transition/:
post:
operationId: publish-study
summary: Transition a study's status
description: 'Transition a study between statuses using one of the available actions.
The following transitions are available:
| Current Status | Action | Resulting Status |
|---|---|---|
| UNPUBLISHED | PUBLISH | ACTIVE |
| UNPUBLISHED | SCHEDULE_PUBLISH | SCHEDULED |
| SCHEDULED | CANCEL_PUBLISH | UNPUBLISHED |
| ACTIVE | PAUSE | PAUSED |
| ACTIVE | STOP | COMPLETED |
| PAUSED | START | ACTIVE |
| PAUSED | STOP | COMPLETED |
**Action details:**
- **PUBLISH**: Publish a draft study so participants can take part. The study must be fully configured.
- **SCHEDULE_PUBLISH**: Schedule a draft study to be published at a future time. A `publish_at` field (ISO 8601 datetime) must be set either on the study or provided in this request.
- **CANCEL_PUBLISH**: Cancel a scheduled publication, returning the study to draft.
- **PAUSE**: Temporarily pause an active study. Participants already taking part can still complete, but no new participants will be recruited.
- **START**: Resume a paused study.
- **STOP**: Stop a study completely. To make it active again you will need to increase the number of places.
To learn more about it check out [help center](https://researcher-help.prolific.com/en/articles/445200-pausing-stopping-a-study)'
tags:
- studies
parameters:
- name: id
in: path
description: Study id
required: true
schema:
type: string
- name: Authorization
in: header
description: 'The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.
Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.
If your token is leaked, delete it and create a new one directly in the app.
In your requests add `Authorization` header with the value `Token <your token>`.'
required: true
schema:
type: string
responses:
'200':
description: Updated
content:
application/json:
schema:
$ref: '#/components/schemas/Study'
'400':
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/StudyTransition'
/api/v1/studies/{id}/test-study:
post:
operationId: create-test-study
summary: Create a test study
description: "### Overview\n- Make sure atleast one test participant is created and exists against the user before hitting this endpoint.\n - To create test participant: POST /api/v1/researchers/participants/\n- Create and publish a test study from a draft study to all the test participants associated with the workspace.\n- This will allow a data collector to test the study as a participant.\n## Prerequisites\n✅ **Required:**\n- At least one active test participant (created via [`POST /api/v1/researchers/participants/`](#))\n- Study must be in draft status\n- Feature enabled for your workspace (contact support if unavailable)\n### Enabling the feature\nThis endpoint is only enabled for select workspaces and will need enabling before the endpoint can be used.\n"
tags:
- studies
parameters:
- name: id
in: path
description: Study id
required: true
schema:
type: string
- name: Authorization
in: header
description: 'The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.
Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.
If your token is leaked, delete it and create a new one directly in the app.
In your requests add `Authorization` header with the value `Token <your token>`.'
required: true
schema:
type: string
responses:
'200':
description: Found
content:
application/json:
schema:
$ref: '#/components/schemas/TestStudySetUpResponse'
'400':
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/v1/studies/{id}/access-details-progress/:
get:
operationId: get-study-access-details-progress
summary: Get taskflow progress
description: 'Returns per-URL allocation progress for a Taskflow study (studies configured with `access_details`).
Each item in `progress` corresponds to one `external_url` from the study''s access details, including how many participants are allocated and any screenout-driven capacity increments.
Returns **404** if the study has no access-details collection (not a Taskflow study).'
tags:
- studies
parameters:
- name: id
in: path
description: Study id
required: true
schema:
type: string
- name: Authorization
in: header
description: 'The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.
Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.
If your token is leaked, delete it and create a new one directly in the app.
In your requests add `Authorization` header with the value `Token <your token>`.'
required: true
schema:
type: string
responses:
'200':
description: Taskflow progress for the study's access details collection.
content:
application/json:
schema:
$ref: '#/components/schemas/StudyAccessDetailsProgress'
'400':
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/v1/studies/{id}/cost/:
get:
operationId: get-study-cost
summary: Show Study cost
description: Returns cost information about the study. Default behaviour is to return cost at the time of the request, but projected cost can be requested via a query parameter.
tags:
- studies
parameters:
- name: id
in: path
description: Study id
required: true
schema:
type: string
- name: is_projected
in: query
description: Return the projected cost of the study
required: false
schema:
type: boolean
default: false
- name: Authorization
in: header
description: 'The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.
Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.
If your token is leaked, delete it and create a new one directly in the app.
In your requests add `Authorization` header with the value `Token <your token>`.'
required: true
schema:
type: string
responses:
'200':
description: Return the total cost for the study
content:
application/json:
schema:
$ref: '#/components/schemas/StudyTotalCost'
'400':
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDetail'
/api/v1/studies/{id}/submissions/:
get:
operationId: get-study-submissions
summary: List study submissions
description: Returns basic information of the submissions, including the study id, participant id, status and start timestamp
tags:
- studies
parameters:
- name: id
in: path
description: Study id
required: true
schema:
type: string
- name: ordering
in: query
description: 'Field to sort results by. Prefix with `-` for descending order. Allowed values: `started_at`, `completed_at`, `status`, `ip`, `time_taken`, `participant_id`, `study_code`.'
required: false
schema:
type: string
- name: Authorization
in: header
description: 'The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.
Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.
If your token is leaked, delete it and create a new one directly in the app.
In your requests add `Authorization` header with the value `Token <your token>`.'
required: true
schema:
type: string
responses:
'200':
description: List submissions
content:
application/json:
schema:
$ref: '#/components/schemas/SubmissionListResponse'
'400':
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDetail'
/api/v1/studies/{id}/submissions/counts/:
get:
operationId: count-study-submissions-by-status
summary: Count study submissions by status
description: Returns a count of the number of submissions per submission status in the study.
tags:
- studies
parameters:
- name: id
in: path
description: Study id
required: true
schema:
type: string
- name: Authorization
in: header
description: 'The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.
Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.
If your token is leaked, delete it and create a new one directly in the app.
In your requests add `Authorization` header with the value `Token <your token>`.'
required: true
schema:
type: string
responses:
'200':
description: Count of number of submissions per submission status for a study
content:
application/json:
schema:
$ref: '#/components/schemas/SubmissionsCountResponse'
'400':
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDetail'
/api/v1/studies/{id}/credentials/report/:
get:
operationId: download-study-credential-report
summary: Download credential usage report
description: Download a CSV report of credential usage for a study. The report includes participant IDs, submission IDs, usernames, and credential status (USED/UNUSED). This endpoint is only available for studies that have credentials configured.
tags:
- studies
parameters:
- name: id
in: path
description: Study id
required: true
schema:
type: string
- name: Authorization
in: header
description: 'The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.
Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.
If your token is leaked, delete it and create a new one directly in the app.
In your requests add `Authorization` header with the value `Token <your token>`.'
required: true
schema:
type: string
responses:
'200':
description: CSV file containing credential usage report
content:
application/json:
schema:
type: object
properties: {}
'400':
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDetail'
/api/v1/studies/{id}/export/:
get:
operationId: export-study
summary: Download demographic data
description: "<span style=\"font-size:x-large\">**Deprecated - please use the new [Demographic Export](https://docs.prolific.com/docs/api-docs/public/#tag/Studies/operation/ExportDemographicData) endpoint instead.**</span>\n\n<span style=\"font-size:x-large\">**This endpoint will be sunset after the 14th of April 2026**</span>\n\nDownload a snapshot of the participants' filter responses at the time that they took your study.\n\nIn addition to the responses to all filters applied to the study (subject to change), you'll also have access to the following data:\n\n* Submission id\n* Participant id\n* Submission status\n* Started date-time\n * Expressed in UTC\n * ISO 8601 formatted\n* Completed date-time\n * Expressed in UTC\n * ISO 8601 formatted\n* Time taken (in seconds)\n* Age\n* Sex\n * Participants were asked the following question: What is your sex, as recorded on legal/official documents?\n* Ethnicity (simplified)\n* First language\n* Current country of residence\n* Nationality\n* Country of birth\n* Student status\n* Employment status\n* Reviewed at date-time\n * Expressed in UTC\n * ISO 8601 formatted\n* Completion code ('entered code')\n* Total approvals\n\nLearn more on [Exporting Prolific demographic data](https://researcher-help.prolific.com/en/article/b2943f)."
tags:
- studies
parameters:
- name: id
in: path
description: Study id
required: true
schema:
type: string
- name: Authorization
in: header
description: 'The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.
Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.
If your token is leaked, delete it and create a new one directly in the app.
In your requests add `Authorization` header with the value `Token <your token>`.'
required: true
schema:
type: string
responses:
'200':
description: Downloaded
content:
application/json:
schema:
type: object
properties: {}
'400':
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/v1/studies/{id}/demographic-export/:
post:
operationId: export-demographic-data
summary: Export demographic data
description: "Create and download a demographic export for a study. This endpoint allows you to export participant demographic data with optional study filter data.\n\n**Filter Support**: This endpoint supports applying demographic filters to export data for participants who match specific criteria.\n\nWhen filters are provided, the export includes both base demographic data (age, sex, country, etc.) and the filters.\n\nWhen no filters are provided, the export includes only base demographic data for all participants who took the study, excluding any study-specific filter responses.\n\n**Export Usage**: Please note that you may only select up to 15 filters per export. You are also limited to 2 different filter export requests.\n\nYou may download the same request as many times as you need. To check your current usage and see your latest export history, use the [Demographic Export History](https://docs.prolific.com/docs/api-docs/public/#tag/Studies/operation/GetDemographicExportHistory) endpoint.\n\n**Basic Data Included**: The export includes the following data fields:\n* Submission ID\n* Participant ID\n* Submission status\n* Started date-time\n * Expressed in UTC\n * ISO 8601 formatted\n* Completed date-time\n * Expressed in UTC\n * ISO 8601 formatted\n* Time taken (in seconds)\n* Age\n* Sex\n * Participants were asked the following question: What is your sex, as recorded on legal/official documents?\n* Ethnicity (simplified)\n* First language\n* Current country of residence\n* Nationality\n* Country of birth\n* Student status\n* Employment status\n* Reviewed at date-time\n * Expressed in UTC\n * ISO 8601 formatted\n* Completion code ('entered code')\n* Total approvals\n\nLearn more on [Exporting Prolific demographic data](https://researcher-help.prolific.com/en/article/b2943f)."
tags:
- studies
parameters:
- name: id
in: path
description: Study ID
required: true
schema:
type: string
- name: Authorization
in: header
description: 'The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.
Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.
If your token is leaked, delete it and create a new one directly in the app.
In your requests add `Authorization` header with the value `Token <your token>`.'
required: true
schema:
type: string
responses:
'200':
description: Demographic data exported successfully
content:
application/json:
schema:
type: object
properties: {}
'400':
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DemographicExportRequest'
/api/v1/studies/{id}/demographic-export-history/:
get:
operationId: get-demographic-export-history
summary: Get demographic export history
description: 'Retrieve the latest demographic export request history for a study. This endpoint returns information about your most recent export request, including the filters used and the total number of export combinations made.
**Usage**: Use this endpoint to check your current export usage and see what filters were used in your latest request. This helps you understand your remaining export quota and track your export history.
**Export Limits**: You are limited to 2 different filter combinations per study. This endpoint helps you track your usage against this limit.
Learn more on [Exporting Prolific demographic data](https://researcher-help.prolific.com/en/article/b2943f).'
tags:
- studies
parameters:
- name: id
in: path
description: Study ID
required: true
schema:
type: string
- name: Authorization
in: header
description: 'The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.
Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.
If your token is leaked, delete it and create a new one directly in the app.
In your requests add `Authorization` header with the value `Token <your token>`.'
required: true
schema:
type: string
responses:
'200':
description: Export history retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/DemographicExportHistoryResponse'
'400':
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/v1/studies/{id}/clone/:
post:
operationId: duplicate-study
summary: Duplicate a study
# --- truncated at 32 KB (136 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/prolific/refs/heads/main/openapi/prolific-studies-api-openapi.yml