Skip to content
How to use
Read an Audience
.md

Read an Audience

Fetch a single audience by its id. The response is a whitelisted, public-safe view of the audience - secrets are never included.

Request

GET /api/v2/analyses/audiences/{id}

curl "https://console.intuizi.com/api/v2/analyses/audiences/88" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Accept: application/json"

The {id} must be numeric. To list every audience your company owns, see List, Get & Delete. This is the same read you poll after creating an audience.

Response

The audience is returned inside the standard envelope under data with its full detail: lifecycle status (see Status Codes), the project it is filed under, who created it, the result count, the dataset blocks with their date windows, and the combination operator (for a two-dataset audience).

{
  "status": "success",
  "code": 200,
  "message": "Resource fetched successfully.",
  "data": [
    {
      "id": 88,
      "name": "Coffee Buyers NYC",
      "status": { "id": 104, "name": "Completed" },
      "is_cohort": false,
      "results_count": 482311,
      "is_activation_allowed": true,
      "eligibility": {
        "allowed": true,
        "reasons": [],
        "metrics": {"unique_eids": 482311, "unique_scids": null, "eid_scid_ratio": null, "is_affinity": false}
      },
      "created_by": { "name": "Jane Doe", "email": "jane.doe@acme.example" },
      "project": { "id": 4, "name": "Retail 2025" },
      "operator": "AND",
      "dataset": [
        { "analysis_type": "WebDomain", "start_date": "01/01/2025", "end_date": "03/31/2025" },
        { "analysis_type": "Apps", "start_date": "01/01/2025", "end_date": "03/31/2025" }
      ],
      "created_at": "2025-04-02 09:21:44",
      "updated_at": "2025-04-02 10:05:12"
    }
  ]
}

is_activation_allowed reports whether the audience can be activated - it is the verdict of the server-side eligibility engine, which checks a device-count floor, Affinity SCID coverage and a retention window. When it is false, eligibility.reasons[] explains why. See the gate table in API Reference - Audiences for the full list of gates and thresholds.

What an audience was built from

A Lookalike Model and an audience built on a cohort both keep their own results as a device list. To get back to the data they came from, follow the ids the read gives you:

  • Lookalike Model - source_audience is the seed audience. Read it with the same GET /api/v2/analyses/audiences/{id}.
  • Cohorts dataset - the Cohorts entry in dataset carries cohort. GET /api/v2/analyses/cohorts/{id} returns that cohort’s source (file, audience or pixel) and, when it was built from an audience, source_audience.

A cohort made from a file has no audience behind it, and older cohorts may not have recorded theirs; for those source_audience is null and the trail ends there. Any of these references is also null when the resource it points to has been deleted or belongs to another company.

Interpreting status

  • 100-103, 105, 108, 109 - still processing. Poll again shortly.
  • 104 Completed - the audience is ready.
  • 107 Additional Info - the build stopped and will not continue. Audience Manager shows the reason on the audience.
  • 4xx - an error state. Inspect the response.

Related

Create an AudienceActivate an Audience