# Audience

The audience is the project's single, merged view of the people it knows: contacts assembled from every data source, the attributes and events they carry, the filters that select them, the segments that keep those filters, and the endpoints that count and retrieve them.

**Language:** en
**Audience:** developer
**TLDR:** A project has ONE audience: every data source feeds it and contacts merge into a single consolidated record per person. You select contacts with the audience query filter (events with the event query filter), measure what the data actually holds with the two probes, get numbers and rows from /audience/count, /audience/search and /audience/scroll, and keep a filter as a named segment. Consent and channel reach are decided when something is sent, never stored inside a segment.
**Search keywords:** audience, unified audience, audience model, CDP, customer data platform, single customer view, consolidated contact, merged contact, who is in my project, how many contacts, audience overview, reach, reachable, audience size, contacts, data sources, datasource, segments, events, attributes, audience API, work with the audience, integrate the audience
**Related pages:** /developers/product-api/audience/contacts-and-attributes, /developers/product-api/audience/query-filter, /developers/product-api/audience/segments
**Docs index (every page):** https://docs.instasent.com/llms.txt
**This zone's index:** https://docs.instasent.com/developers/product-api/llms-full.txt
**This page:** https://docs.instasent.com/developers/product-api/audience/overview/ (HTML) · https://docs.instasent.com/developers/product-api/audience/overview.md (Markdown)

Instasent is a customer data platform, and the audience is the thing it is a platform for. Everything else in the Product API either feeds the audience, asks it a question, or acts on the answer. A project holds exactly **one** audience: not a set of lists you maintain in parallel, but a single merged view of every person the project knows, assembled from every data source that ever sent that project data.

This section is the working guide to that audience over the API: what it is made of, how to ask it questions, how to check that the answer means what you think it means, and how to keep a question you want to reuse.

## The model

```mermaid
flowchart TD
    DS1[Data source: CRM]
    DS2[Data source: e-commerce]
    DS3[Data source: Ingest API]
    DSC[Datasource contacts<br/>one record per source]
    AUD[Audience contact<br/>one consolidated record per person]
    EV[Events<br/>what the person did]
    QF[Query filter<br/>selects contacts]
    SEG[Segment<br/>a saved filter]
    CMP[Campaigns and automations]

    DS1 --> DSC
    DS2 --> DSC
    DS3 --> DSC
    DSC -->|merged by the project's merging attributes| AUD
    EV -->|attached to the person| AUD
    AUD --> QF
    QF -->|saved with a name| SEG
    QF --> CMP
    SEG --> CMP
```

Five nouns carry the whole section:

- **Data source** is a stream of contacts and events feeding one project. A project can have many, and each keeps its own original records.
- **Datasource contact** is the record exactly as it arrived in one source.
- **Audience contact** is the consolidated projection of every datasource contact that turned out to be the same person. This is what you query, count and message. It is not a copy of one source's record: it is the merged result, and no single field on it is guaranteed to have come from any particular source.
- **Event** is an immutable record of something the person did. Events hang off the audience contact, so one person has one timeline no matter how many sources reported parts of it.
- **Segment** is a saved filter, not a stored list. It holds a question, and the answer is recomputed when it is used.

> **Note**: A segment does not contain contacts. It contains the filter that selects them, so its membership changes as the audience changes. That is the single most common wrong assumption about this API, and it is worth fixing before writing any code: see [Segments](/developers/product-api/audience/segments).

## What lives in this section

- [Contacts and attributes](/developers/product-api/audience/contacts-and-attributes) - How records from several sources become one contact, and what system and custom attributes it carries.
- [Events](/developers/product-api/audience/events) - The event model: types, parameters, the project's catalogue, and what actually arrives.
- [Query filter](/developers/product-api/audience/query-filter) - The grammar that selects contacts: attribute, event and segment conditions.
- [Event query filter](/developers/product-api/audience/event-query-filter) - The grammar that selects events directly, with its own aggregation surface.
- [Probes](/developers/product-api/audience/probes) - Measure what the audience actually contains before you filter it. Probe first, then filter.
- [Counting and retrieval](/developers/product-api/audience/counting-and-retrieval) - Count, search, scroll: which endpoint answers which question, and what each returns.
- [Segments](/developers/product-api/audience/segments) - Keep a filter as a named segment, read it back, audit where it is used.

## How big is my audience

Before composing anything, the cheapest question has its own endpoint. `GET /project/{project}/audience/overview` returns the project's total contacts and, for every channel the project can send on, how many of them are actually reachable under the project's own consent policy, together with what each other policy would reach.

[`GET /project/{project}/audience/overview` - Total contacts plus reachable contacts per channel, and the full policy ladder.](/developers/product-api/reference)

```bash
curl "$BASE/audience/overview" \
  -H "Authorization: Bearer $INSTASENT_TOKEN"
```

Two things about the answer. It carries aggregate numbers only, with no contact rows, so it is not restricted by the project's data policy and needs nothing beyond `PROJECT_AUDIENCE_READ`. And its counters are cached, with an age reported in `computedAgo` that you should narrate along with the figure rather than presenting it as a live total. Channels the project cannot send on simply do not appear.

Use it when the question is "what is my audience" or "what would I gain by asking for opt-in". Use [`/audience/count`](/developers/product-api/audience/counting-and-retrieval) when the question is about a specific filter.

## Three rules worth knowing before you start

### The contact is a projection, not a record

An audience contact is built from every source that touched that person, and the project's priority rules pick the winner when two sources disagree about the same attribute. So "this contact came from the CRM" is not a meaningful statement about a value: the contact came from all of them. Narrowing anything by `datasource` selects contacts a source **contributed to**, never the values it supplied. The consequences are worked through in [Contacts and attributes](/developers/product-api/audience/contacts-and-attributes).

### Consent is not part of the audience question

Who the contacts **are** and who may be **messaged** are separate questions, resolved at different moments. A filter and a segment answer the first. Reach under a channel's consent policy is resolved when something is sent, and it is available on demand through the `filterCompliance` key of a count. Never bake consent into a saved segment.

### Probe before you filter

A condition on an attribute almost nobody filled, or on a value spelled differently in the data, is a perfectly valid filter that selects nobody. It returns `200`. Nothing errors. The two [probes](/developers/product-api/audience/probes) exist to close that gap, and reaching for them costs one request.

## Scopes

The whole section runs on the audience scopes described in the [Product API guide](/developers/product-api/guide#tokens-and-scopes). In short:

| You want to                                              | Scope                                         |
| -------------------------------------------------------- | --------------------------------------------- |
| Read a contact, read segments, count, probe              | `PROJECT_AUDIENCE_READ`                       |
| Scroll contacts, or scroll a segment                     | `PROJECT_AUDIENCE_LIST` (plan-gated)          |
| See phone, email, country and names on returned contacts | `PROJECT_AUDIENCE_DATA_BASIC` (plan-gated)    |
| Read events on a contact                                 | `PROJECT_AUDIENCE_DATA_EVENTS` (plan-gated)   |
| Save a filter as a segment                               | `PROJECT_SEGMENT_WRITE`                       |
| Run your own aggregations                                | `PROJECT_AGGREGATIONS` (granted by Instasent) |

> **Warning**: Scopes and plan are two gates, not one. A scope your token carries still returns redacted data if the organization's subscription does not include it. Design against **Basic** access and verify what actually comes back before assuming a field is there.

## What's next

- **[Contacts and attributes](/developers/product-api/audience/contacts-and-attributes)**: the merge model and the attribute catalogue, which is where most integration surprises come from.
- **[Query filter](/developers/product-api/audience/query-filter)**: the grammar, once you know what you are filtering on.
- **[Full API Reference](/developers/product-api/reference)**: every audience, event and segment endpoint.

---

This is one page of the Instasent documentation. For the complete machine-readable index of every guide and API reference, fetch https://docs.instasent.com/llms.txt — start there for full context.