> ## Documentation Index
> Fetch the complete documentation index at: https://docs.userjourneys.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Studies

> List and retrieve your interview studies — check capacity, limits, and whether a study is accepting responses.

A study is a research configuration: the questions, target audience, and settings for a set of interviews. Each study has a public interview link that you send to respondents.

***

## `GET /v1/studies`

List all active studies for your project.

Returns studies with their current usage and whether they're accepting new responses.

### Request

<ParamField header="Authorization" type="string" required>
  Bearer token. See [Authentication](/api/authentication).
</ParamField>

<ParamField query="limit" type="integer">
  Number of studies to return. Default `20`, max `100`.
</ParamField>

<ParamField query="starting_after" type="string">
  Cursor for pagination. Pass the `id` of the last study from the previous page.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl https://app.userjourneys.ai/api/v1/studies \
    -H "Authorization: Bearer uj_live_your_key_here"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://app.userjourneys.ai/api/v1/studies",
    {
      headers: {
        Authorization: "Bearer uj_live_your_key_here",
      },
    }
  );
  const { data, has_more } = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://app.userjourneys.ai/api/v1/studies",
      headers={"Authorization": "Bearer uj_live_your_key_here"},
  )
  data = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "object": "list",
    "data": [
      {
        "id": "e5f6a7b8-1234-56cd-ef78-222222222222",
        "object": "study",
        "name": "Onboarding Feedback",
        "status": "active",
        "interview_link": "https://app.userjourneys.ai/i/xK9mR2pQ",
        "accepting_responses": true,
        "supported_languages": ["en", "es"],
        "limits": {
          "monthly": { "limit": 200, "used": 45 },
          "weekly": { "limit": 50, "used": 12 }
        },
        "created_at": "2026-03-01T00:00:00.000Z"
      }
    ],
    "has_more": false
  }
  ```
</ResponseExample>

<Tip>
  Cache this response for a few minutes. Study capacity doesn't change often, and caching avoids unnecessary API calls.
</Tip>

***

## `GET /v1/studies/:id`

Retrieve a single study with full details including questions, research goal, and interview count.

### Request

<ParamField header="Authorization" type="string" required>
  Bearer token. See [Authentication](/api/authentication).
</ParamField>

<ParamField path="id" type="string" required>
  Study ID (UUID).
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl https://app.userjourneys.ai/api/v1/studies/e5f6a7b8-1234-56cd-ef78-222222222222 \
    -H "Authorization: Bearer uj_live_your_key_here"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://app.userjourneys.ai/api/v1/studies/e5f6a7b8-1234-56cd-ef78-222222222222",
    {
      headers: {
        Authorization: "Bearer uj_live_your_key_here",
      },
    }
  );
  const study = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://app.userjourneys.ai/api/v1/studies/e5f6a7b8-1234-56cd-ef78-222222222222",
      headers={"Authorization": "Bearer uj_live_your_key_here"},
  )
  study = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "e5f6a7b8-1234-56cd-ef78-222222222222",
    "object": "study",
    "name": "Onboarding Feedback",
    "status": "active",
    "interview_link": "https://app.userjourneys.ai/i/xK9mR2pQ",
    "accepting_responses": true,
    "supported_languages": ["en", "es"],
    "limits": {
      "monthly": { "limit": 200, "used": 45 },
      "weekly": { "limit": 50, "used": 12 }
    },
    "research_goal": "Understand user onboarding experience",
    "product_name": "Acme App",
    "questions": [
      { "text": "What was your first impression of the product?" },
      { "text": "What almost stopped you from signing up?" }
    ],
    "interview_count": 45,
    "created_at": "2026-03-01T00:00:00.000Z"
  }
  ```
</ResponseExample>

Returns `404` if the study doesn't exist or doesn't belong to your project.

***

## Study object

<ResponseField name="id" type="string">
  Study ID (UUID).
</ResponseField>

<ResponseField name="object" type="string">
  `"study"`
</ResponseField>

<ResponseField name="name" type="string">
  Display name.
</ResponseField>

<ResponseField name="status" type="string">
  `"active"`, `"paused"`, or `"draft"`.
</ResponseField>

<ResponseField name="interview_link" type="string">
  Public URL for respondents. Append `?reference_id=your_user_id` to track who completes the interview.
</ResponseField>

<ResponseField name="accepting_responses" type="boolean">
  `true` when the study is active and within all usage limits.
</ResponseField>

<ResponseField name="supported_languages" type="string[]">
  Language codes the study supports (e.g. `["en", "es"]`).
</ResponseField>

<ResponseField name="limits" type="object">
  <Expandable title="properties">
    <ResponseField name="monthly" type="object">
      <Expandable title="properties">
        <ResponseField name="limit" type="integer | null">
          Monthly interview cap. `null` if unlimited.
        </ResponseField>

        <ResponseField name="used" type="integer">
          Interviews used in the current billing period.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="weekly" type="object">
      <Expandable title="properties">
        <ResponseField name="limit" type="integer | null">
          Weekly interview cap. `null` if unlimited.
        </ResponseField>

        <ResponseField name="used" type="integer">
          Interviews used this week (Mon–Sun UTC).
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp.
</ResponseField>

### Detail-only fields

These fields are only included in `GET /v1/studies/:id` responses:

<ResponseField name="research_goal" type="string | null">
  The research objective for this study.
</ResponseField>

<ResponseField name="product_name" type="string | null">
  The product being researched.
</ResponseField>

<ResponseField name="questions" type="object[]">
  The interview questions.

  <Expandable title="properties">
    <ResponseField name="text" type="string">
      The question text.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="interview_count" type="integer">
  Total number of completed interviews for this study.
</ResponseField>