---
title: "Check stimulus access"
method: GET
path: "/api/v1/stimuli/{stimulus_id}/access"
tags: ["Stimuli"]
---

# Check stimulus access

`GET /api/v1/stimuli/{stimulus_id}/access`

## Request

- Base URL: `https://app.voicepanel.com`
- URL: `https://app.voicepanel.com/api/v1/stimuli/{stimulus_id}/access`
- Auth: HTTP bearer

Check whether one response can see one stimulus. Use it on the server that hosts a prototype: admit a participant only while `allowed` is true. The check records nothing, so a participant can open the link again, and every call gives the same answer while the response is active. This makes a prototype link multi-use. For a single-use link, use [POST /api/v1/stimuli/{stimulus_id}/claim](#tag/stimuli/post-api-v1-stimuli-stimulus_id-claim) instead. When a participant opens a website, prototype, mobile app, or html stimulus, the URL carries both ids as query parameters: `voicepanel_response_id` and `voicepanel_stimulus_id`. Stimulus IDs also appear on each stimulus in a study's plan. A token with only the `stimuli:check_access` scope can call this endpoint.

## Path parameters

- `stimulus_id` string, required

## Query parameters

- `response_id` string, required

## Response `200`

Successful response

- StimulusAccess: Whether one response can see one stimulus
  - `allowed` boolean, required: True if the response can see the stimulus. The study plan must reference the stimulus and the response must be active. A response is active while its status is `opened` or `in_progress` and its distribution is `published`. A paused or completed distribution closes the study, so its responses are inactive. A preview response is always active, because it is the researcher's own test run. A participant who leaves stays active until the response times out, which can take up to about 15 minutes.
  - `reason` 'response_inactive' | 'stimulus_not_in_study', nullable, required: Why access is refused. `stimulus_not_in_study`: the plan of the response's study does not reference the stimulus. `response_inactive`: the response is completed, incomplete, or not yet opened, or its distribution is paused or completed. A preview response never gets this reason. Null when `allowed` is true.

## 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.
- `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.

---

[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)