Change LogAPI RoadmapDiagrams
Guides

Audience Quotas

Suggest Edits

🚧

Currently in early access, please contact your account manager for more information

Use quota endpoints to limit how many participants come from each audience segment. This is helpful if you want a balanced, representative sample - but totally optional.

Quotas are currently only available for unmoderated studies and surveys that have auto-invite enabled.

We currently support only one quota per project, based on demographic categories.

Quota Categories (v1)

The following demographic fields are supported in v1:

FieldExamples
genderfemale, male, other
age18-20, 21-29, 30-39
ethnicityamericanindianalaskannative, hispaniclatino, blackorafricanamerican
location (Country Code ISO 3166-1 alpha-2)US, GB, BR

Eligibility Constraints

  • Project targetResearchMethodology must be unmoderatedStudy or survey
  • Auto-invite must be enabled
  • Quotas must be defined before project is published and can't be edited once the project has been published

Sample Workflow

  1. Create an unmoderated/survey project with auto-invite enabled via POST /v1/projects.
  2. Define quotas with POST /v1/projects/{projectId}/quota.
  3. Publish project - we will match and invite participants based on your desired quota segments.
  4. Monitor fill progress with GET /v1/projects/{projectId}/quota

Creating quotas

POST /v1/projects/{projectId}/quota

{
  "version": "v1",
  "criteria": {
    "category": "age",
    "segments": [
      {
        "value": "male",
        "percentage": 50
      },
      {
        "value": "female",
        "percentage": 50
      }
    ]
  }
}

{
  "id": "68086546545de68c1bc1bc1b",
  "projectId": "68084868666de68c1b4f3412",
  "version": "v1",
  "totalTarget": 1,
  "status": "IN_PROGRESS",
  "criteria": {
    "category": "gender",
    "segments": [
      {
        "value": "male",
        "percentage": 50,
        "id": "1"
      },
      {
        "value": "female",
        "percentage": 50,
        "id": "2"
      }
    ]
  },
  "progress": {
    "currentCount": 0,
    "targetCount": 50
  },
  "createdAt": "2025-05-15T03:44:44.482Z",
  "updatedAt": "2025-05-15T03:44:44.482Z"
}

Monitoring quota fill rates

GET /v1/projects/{projectId}/quota

{
  "id": "68086546545de68c1bc1bc1b",
  "projectId": "68084868666de68c1b4f3412",
  "version": "v1",
  "totalTarget": 10,
  "status": "IN_PROGRESS",
  "criteria": {
    "category": "gender",
    "segments": [
      {
        "value": "male",
        "percentage": 50,
        "id": "1"
      },
      {
        "value": "female",
        "percentage": 50,
        "id": "2"
      }
    ]
  },
  "progress": {
    "1": {
      "currentCount": 2,
      "targetCount": 5
    },
    "2": {
      "currentCount": 1,
      "targetCount": 5
    }
  },
  "createdAt": "2025-05-15T03:44:44.482Z",
  "updatedAt": "2025-05-15T03:44:44.482Z"
}

References

Example of how quotas are created via the Respondent Researcher Platform

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

Updated about 7 hours ago