---
title: "Pause, resume or complete a distribution"
method: PATCH
path: "/api/v1/distributions/{distribution_id}/status"
tags: ["Distributions"]
---

# Pause, resume or complete a distribution

`PATCH /api/v1/distributions/{distribution_id}/status`

## Request

- Base URL: `https://app.voicepanel.com`
- URL: `https://app.voicepanel.com/api/v1/distributions/{distribution_id}/status`
- Auth: HTTP bearer

Change the status of a distribution that is already published. A study collects responses only while it has a `published` distribution, so this is how a study is paused or closed. `published` -> `paused` stops new participants from starting; `paused` -> `published` resumes; `published` or `paused` -> `completed` closes the distribution for good, and a completed panel distribution returns its unused credits. A `completed` distribution cannot change status again; duplicate it instead. `in_review` -> `draft` cancels a review request. Any other transition is a 409. A `draft` or `in_review` distribution goes live through the publish endpoint, which also charges credits and freezes the study snapshot. For a panel distribution, the provider project is paused, resumed or closed in the background after this call returns.

## Path parameters

- `distribution_id` string, required

## Request body

- DistributionStatusUpdateBody: Change the status of a distribution
  - `status` 'published' | 'paused' | 'completed' | 'draft', required: The status to move to. `paused` stops a published distribution from taking new participants. `published` resumes a paused one. `completed` closes a published or paused one for good and, for a panel distribution, returns unused credits. `draft` cancels a review request on an `in_review` distribution. A draft or in_review distribution goes live through the publish endpoint, not through this one.

## Response `200`

The distribution with its new status

- Distribution: A distribution of a study to participants
  - `id` string, required: Distribution ID
  - `url` string, nullable, required: Public link participants open to take the study. Set for link distributions only; null for every other type.
  - `study_id` string, required: ID of the study this distribution belongs to
  - `name` string, nullable, required: Name of the distribution
  - `description` string, nullable, required: Description of the distribution
  - `type` 'link' | 'service' | 'email' | 'website' | 'app' | 'panel' | 'simulation', required: How the study is distributed to participants
  - `status` 'draft' | 'published' | 'paused' | 'completed' | 'in_review', required: Current status of the distribution
  - `distribution_provider` 'respondent' | 'user_interviews' | 'prolific' | 'terac', nullable, required: Third-party panel provider
  - `distribution_provider_id` string, nullable, required: External provider project ID
  - `config` object, required: Provider-specific configuration
  - `incentive` object, nullable, required: Incentive configuration for link distributions
  - `quota_limit` number, nullable, required: Maximum number of responses
  - `quota_frequency` 'lifetime' | 'monthly' | 'weekly' | 'daily', required: How often the quota resets
  - `quota_usage` integer, required: Responses counted against the current quota
  - `segment_quotas` union, required
    - string
    - number
    - boolean
    - Json[]
    - object
  - `screener_questions` Json[], required: Screener questions for qualifying participants
    - union
      - string
      - number
      - boolean
      - Json[]
      - object
  - `targeting_condition` union, required
    - string
    - number
    - boolean
    - Json[]
    - object
  - `device_targeting` union, required
    - string
    - number
    - boolean
    - Json[]
    - object
  - `default_response_language` string, nullable, required: Default language for responses
  - `collect_email` boolean, required: Whether to collect participant email
  - `screen_email` boolean, required: Whether to screen participants against an email list
  - `email_list_id` string, nullable, required: Email list used to screen or invite participants
  - `automatic_invites` boolean, required: Whether participants are invited automatically
  - `key` string, nullable, required: Snippet key used to trigger an intercept distribution
  - `traffic_threshold` number, nullable, required: Share of eligible traffic shown the study, out of 1,000,000
  - `complete_redirect_url` string, nullable, required: URL to redirect to after completion
  - `screen_out_redirect_url` string, nullable, required: URL to redirect screened-out participants
  - `quota_full_redirect_url` string, nullable, required: URL to redirect when quota is full
  - `quality_terminate_redirect_url` string, nullable, required: URL to redirect participants terminated for quality
  - `study_data` union, required
    - string
    - number
    - boolean
    - Json[]
    - object
  - `is_archived` boolean, required: Whether the distribution is archived
  - `seq_num` integer, nullable, required: Sequence number within the study
  - `published_at` string, date-time, nullable, required: When the distribution was published
  - `last_completed_at` string, date-time, nullable, required: When the latest response completed
  - `created_by` string, nullable, required: ID of the user who created the distribution
  - `created_at` string, date-time, nullable, required
  - `updated_at` string, date-time, nullable, required
  - `pretranslations` object[]: Locales with a stored translation of the distribution. Not returned by publish.
    - `locale` string, required

## Other responses

- `400`: Bad request. `code` is `validation_error` when a field is invalid or a query parameter is unknown, with the field paths in `details`, or `bad_request` otherwise.
- `401`: Unauthorized. The token is missing, invalid, or has no user.
- `403`: Forbidden. The token has no access to this resource.
- `404`: Not found. The resource does not exist or belongs to another account.
- `409`: Conflict. The write disagrees with the current state of the resource.
- `429`: Too many requests. The account used its API rate limit. `code` is `too_many_requests`. Wait for the number of seconds in `Retry-After`, then retry.
- `500`: Internal error. Quote `request_id` when you contact support.
- `503`: Service unavailable. A dependency did not answer and nothing was saved. Retry later.

---

[API](https://skmtc.dev/voicepanel/apis/voicepanel-api.md) - [All operations](https://skmtc.dev/voicepanel/apis/voicepanel-api/llms.txt) - [OpenAPI document](https://skmtc.dev/voicepanel/apis/voicepanel-api/revisions/ee41535c5694?raw)