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

# Panel targeting quotas

> Set fixed interview targets for selected panel attribute options while leaving remaining capacity open

Panel targeting quotas let you reserve part or all of a panel launch for specific answers to eligible single-select targeting attributes. You can use them with either:

* `POST /api/public/v1/studies/{study_id}/launch-panel`
* `POST /api/public/v1/studies/create-and-launch-panel`

## Find attribute and option IDs

Call `GET /api/public/v1/targeting-attributes/` before building the launch request. Use each catalog row's `qualification_id` and the `option_id` values from its `options` array.

For an existing study, the targeted qualification must already be configured in the study's `targeting_attributes`. With `create-and-launch-panel`, configure the qualification in `study.targeting_attributes` and put its launch quotas in `panel.targeting_attributes`.

## Playground format

In the API playground, add one `option_targets` item for every fixed target. `option_id` is the targeting catalog option ID, and `target` is the fixed interview count.

```bash theme={null}
curl --request POST \
  --url https://api.userintuition.ai/api/public/v1/studies/{study_id}/launch-panel \
  --header 'Authorization: Bearer <your_api_key_or_jwt_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "target": 20,
    "incident_rate": 25,
    "country_code": "US",
    "targeting_attributes": [
      {
        "qualification_id": 2,
        "option_targets": [
          {
            "option_id": 1,
            "target": 8
          }
        ]
      }
    ]
  }'
```

This reserves 8 interviews for option `1`. Every other qualifying option remains **Open** and shares the remaining 12 interviews.

## Object map format

Direct API clients can continue to send `option_targets` as an object map. Its keys are option IDs and its values are fixed interview counts:

```json theme={null}
{
  "qualification_id": 2,
  "option_targets": {
    "1": 8
  }
}
```

Both formats have identical behavior and validation. The array form exists because the documentation playground cannot preserve numeric object keys.

## Create a study and launch its panel

```json theme={null}
{
  "study": {
    "name": "US customer study",
    "recruiting_method": "panel",
    "targeting_attributes": [
      {
        "qualification_id": 2,
        "allowed_options": [1, 2],
        "disallowed_options": []
      }
    ]
  },
  "panel": {
    "target": 20,
    "incident_rate": 25,
    "country_code": "US",
    "targeting_attributes": [
      {
        "qualification_id": 2,
        "option_targets": [
          {
            "option_id": 1,
            "target": 8
          }
        ]
      }
    ]
  }
}
```

## Validation rules

* Only eligible single-select attributes and the panel age attribute can have launch targets.
* The attribute must have at least two qualifying options.
* Every option target must be a positive whole number.
* Targets for one attribute cannot add up to more than the panel's `target`.
* If the configured targets add up to less than the panel target, at least one qualifying option must be omitted from `option_targets` and left Open.
* The array format cannot contain the same `option_id` more than once.
* A fully specified distribution is valid when its option targets add up exactly to the panel target.
* Unknown or disqualifying option IDs are rejected.
* Each `qualification_id` can appear only once in a launch request.

<Note>
  A dry run validates targeting quotas with the same rules as a real launch, without creating a study or panel.
</Note>