Audience Quotas

Use quota endpoints to cap how many participants you invite from each audience segment. A quota is optional. One quota per project. Set the configuration with PUT /v1/projects/{projectId}/quotas. You can also send the same { version: "v2", groups[] } body as quotas on POST /v1/projects. /v1/projects/{projectId}/quota is an alias of /quotas. A project with no quota returns 200 and { version: "v2", groups: [] }. 404 is only for a project that does not exist. A quota holds at most 20 groups, and a group at most 50 segments; a configuration over either cap is rejected with a 400.

Conditions

Each segment has a rule tree. Nodes are kind: "group" (AND / OR children) or kind: "condition". Age is a numeric attribute, not age-band enums.

Source	Operators	Fields
Age	`range`, `gt`, `lt`	`range`: inclusive `min` and/or `max`. `gt` / `lt`: `value` (strict). `in` / `notIn` is rejected (`in is not available for age; it takes range, gt, lt`).
Categorical attributes (gender, ethnicity, country, industry, job title, company size, seniority, education)	`in`, `notIn`	`values` (strings; job title ids are resolved to title families on save)
Screener RADIO / CHECKBOX	`any`, `all`, `none`	`questionUid`, `answerUids`. `all` is CHECKBOX only.
Screener CHECKBOX	`count`	`questionUid`, `op` (`eq`, `ne`, `gt`, `gte`, `lt`, `lte`), `value` (a non-negative integer). Compares how many options the participant selected with `value`; `gt` and `lt` are strict, `gte` and `lte` inclusive.
External screener RADIO / CHECKBOX	`any`, `all`, `none`	`questionId`, `optionIds` — the `id`s of the question’s declared `options`. `all` is CHECKBOX only.
External screener CHECKBOX	`count`	`questionId`, `op`, `value`, as above.

A participant who skipped a question matches no condition on it, none and count included; a CHECKBOX answered with nothing selected counts as 0. Targets are { op: "min" }, { op: "max" }, { op: "exact" } (each with value) or { op: "track" } for counted-but-uncapped buckets. Address a group’s implicit leftover bucket with segmentId: "no-match".

Sample workflow

Create a project via POST /v1/projects, optionally with quotas.
Create or replace the quota with PUT /v1/projects/{projectId}/quotas (allowed on draft and published projects).
Publish. Matching and invites consume the quota. A public invite is always admitted: the invite succeeds, consumption is recorded, and the bucket may go over target. There is no 409 on this path.
Read fill with GET /v1/projects/{projectId}/quotas. Each screener response that occupies a quota carries quotaAssignment (segments[], tier, revision, assignedAt, tierChangedAt).
Subscribe to QUOTAS.SEGMENT_FILLED and QUOTAS.FILLED on your webhook.

Create or replace

PUT /v1/projects/{projectId}/quotas A group or segment whose id matches an existing one keeps its progress. An omitted or new id is a new bucket at zero. The response includes changes (created, preserved, removed, rebucketed, externalFillsDropped, overTarget) and warnings.

{
  "version": "v2",
  "groups": [
    {
      "id": "gender",
      "name": "Gender",
      "segments": [
        {
          "id": "female",
          "name": "Female",
          "rule": {
            "kind": "group",
            "connector": "AND",
            "children": [
              {
                "kind": "condition",
                "condition": {
                  "source": "attribute",
                  "attribute": "gender",
                  "op": "in",
                  "values": ["female"]
                }
              }
            ]
          },
          "target": { "op": "max", "value": 10 }
        },
        {
          "id": "male",
          "name": "Male",
          "rule": {
            "kind": "group",
            "connector": "AND",
            "children": [
              {
                "kind": "condition",
                "condition": {
                  "source": "attribute",
                  "attribute": "gender",
                  "op": "in",
                  "values": ["male"]
                }
              }
            ]
          },
          "target": { "op": "max", "value": 10 }
        }
      ]
    }
  ]
}

{
  "id": "68086546545de68c1bc1bc1b",
  "projectId": "68084868666de68c1b4f3412",
  "version": "v2",
  "revision": 1,
  "filled": false,
  "closed": false,
  "groups": [
    {
      "id": "gender",
      "name": "Gender",
      "filled": false,
      "closed": false,
      "minProtected": false,
      "segments": [
        {
          "id": "female",
          "name": "Female",
          "rule": {
            "kind": "group",
            "connector": "AND",
            "children": [
              {
                "kind": "condition",
                "condition": {
                  "source": "attribute",
                  "attribute": "gender",
                  "op": "in",
                  "values": ["female"]
                }
              }
            ]
          },
          "target": { "op": "max", "value": 10 },
          "progress": {
            "pending": 0,
            "qualified": 0,
            "invited": 0,
            "attended": 0,
            "externalFills": 0
          },
          "filled": false,
          "closed": false,
          "overTarget": false
        },
        {
          "id": "male",
          "name": "Male",
          "rule": {
            "kind": "group",
            "connector": "AND",
            "children": [
              {
                "kind": "condition",
                "condition": {
                  "source": "attribute",
                  "attribute": "gender",
                  "op": "in",
                  "values": ["male"]
                }
              }
            ]
          },
          "target": { "op": "max", "value": 10 },
          "progress": {
            "pending": 0,
            "qualified": 0,
            "invited": 0,
            "attended": 0,
            "externalFills": 0
          },
          "filled": false,
          "closed": false,
          "overTarget": false
        }
      ],
      "noMatch": {
        "target": { "op": "track" },
        "progress": {
          "pending": 0,
          "qualified": 0,
          "invited": 0,
          "attended": 0,
          "externalFills": 0
        },
        "filled": false,
        "closed": false,
        "overTarget": false
      }
    }
  ],
  "changes": {
    "created": [
      { "groupId": "gender", "segmentId": "female" },
      { "groupId": "gender", "segmentId": "male" }
    ],
    "preserved": [],
    "removed": [],
    "rebucketed": 0,
    "externalFillsDropped": [],
    "overTarget": []
  },
  "warnings": [],
  "createdAt": "2026-09-08T03:44:44.482Z",
  "updatedAt": "2026-09-08T03:44:44.482Z"
}

Update targets

PATCH /v1/projects/{projectId}/quotas/targets Sparse array. One entry per bucket; a duplicate (groupId, segmentId) is 400. Omitted buckets are untouched. Tracked-only is { "op": "track" }. Rules and progress are not rewritten.

Read

GET /v1/projects/{projectId}/quotas Config and progress together, plus derived filled, closed, and per-group minProtected. version discriminates the body: "v2" is the document above; "v1" is a legacy { criteria, progress, totalTarget, status } shape still returned for projects that have not been moved.

External fills

PUT /v1/projects/{projectId}/quotas/external-fills Bare array of { groupId, segmentId, count }. Absolute counts, applied atomically.

Delete

DELETE /v1/projects/{projectId}/quotas Returns 204. The next GET is the empty V2 configuration. Assignments on existing responses are not released by delete.

References

Example of how quotas are created via the Respondent Researcher Platform

Example of how fill progress is presented in the Respondent Researcher Platform

Getting started

Projects

Screeners and Responses

Messaging

Webhooks

Guides

Conditions

Sample workflow

Create or replace

Update targets

Read

External fills

Delete

References

​Conditions

​Sample workflow

​Create or replace

​Update targets

​Read

​External fills

​Delete

​References

Conditions

Sample workflow

Create or replace

Update targets

Read

External fills

Delete

References