---
title: "Map an audience"
method: POST
path: "/exploration/map"
tags: ["Audience Exploration"]
---

# Map an audience

`POST /exploration/map`

## Request

- Base URL: `https://www.fandom.ai/api/v1`
- URL: `https://www.fandom.ai/api/v1/exploration/map`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/skilledstars/apis/super-fans-enterprise-api/docs/exploration/map/post.ts> (a function with typed inputs; its response is checked against the schema)

The channels an audience also watches, grouped by shared commenters, with people counts. Built from real YouTube comment data; takes a few seconds the first time. Size 160 is the app's Expand map.

Scope: `exploration:read`.

## Request body

- object
  - `sources` union[], required: What to map. Combine up to 8.
    - union
      - object
        - `type` 'channel', required
        - `channelId` string, required: YouTube channel id, e.g. `UCX6OQ3DkcsbYNE6H8uQQuVA`.
      - object
        - `type` 'query', required
        - `query` string, required: Describe the audience in plain words.
      - object
        - `type` 'brand', required
        - `brandId` string, required: Brand id.
      - object
        - `type` 'audience', required
        - `audienceId` string, required: Audience id.
        - `preset` boolean: One of Fandom's own audiences, as search_exploration says. Worked out when you leave it out.
      - object
        - `type` 'channels', required
        - `channelIds` string[], required: A group of channels, mapped as one audience.
        - `label` string, required: What to call the group.
        - `of` string[]: What the group was taken from, outermost first, as a group's `expand` says.
      - object
        - `type` 'topic', required
        - `topic` string, required: A topic from search_exploration.
        - `kind` 'conversation' | 'content', required: What viewers talk about, or what channels publish.
      - object
        - `type` 'campaign', required
        - `campaignId` string, required: Campaign id.
      - object
        - `type` 'link', required
        - `url` string, required: A YouTube channel or video link, an @handle, or a website.
      - object
        - `type` 'inclusion_list', required
        - `listId` string, required: A finished inclusion list: its top channels are mapped.
      - object
        - `type` 'project', required
        - `projectId` string, required: A project: its most relevant channels are mapped.
        - `selection` string: Part of its map: a cluster number or name.
        - `channelIds` string[]: Or exactly these channels of it.
  - `size` integer: Most channels on the map. Default 110.

## Response `200`

Success

- object
  - `title` string, required
  - `url` string, required: This map in the app.
  - `builtAt` string, required
  - `canExpand` boolean, required: A bigger map of the same sources may hold more channels: ask for size 160.
  - `notes` string[], required: Coverage caveats worth showing to people.
  - `audience` object, nullable, required: People counts. Null when they could not be measured in time.
    - `corePeople` number, required
    - `totalPeople` number, required
    - `totalComments` number, required
  - `groups` object[], required
    - `id` number, required
    - `name` string, required
    - `kind` 'core' | 'adjacent' | 'unconnected', required: `core` is the audience you asked about; `adjacent` groups share its commenters.
    - `description` string, required: Who these people are.
    - `themes` string[], required
    - `relevance` number, nullable, required
    - `channelIds` string[], required
    - `expand` object, required: A source for build_exploration_map: this group as its own map.
      - `type` 'channels', required
      - `channelIds` string[], required
      - `label` string, required
    - `people` number, nullable, required: Distinct commenters (sampled, then scaled).
    - `reach` number, nullable, required: Share of the core audience found here, 0–1.
    - `concentration` number, nullable, required: Share of these people who are in the core audience, 0–1.
    - `fanDensity` number, nullable, required: How many times more common the core audience is here than among everyone we see on YouTube (1.3 = 30% more). Null for the core itself.
  - `channels` object[], required
    - `channelId` string, required
    - `title` string, required
    - `handle` string, nullable, required
    - `imageUrl` string, required
    - `subscribers` number, required
    - `country` string, nullable, required
    - `groupId` number, required
    - `seed` boolean, required: One of the channels the map was built from.
    - `relevance` number, nullable, required
    - `sharedCommenters` number, required
    - `audienceThemes` string[], required
    - `contentThemes` string[], required
    - `people` number, nullable, required: Distinct commenters (sampled, then scaled).
    - `reach` number, nullable, required: Share of the core audience found here, 0–1.
    - `concentration` number, nullable, required: Share of these people who are in the core audience, 0–1.
    - `fanDensity` number, nullable, required: How many times more common the core audience is here than among everyone we see on YouTube (1.3 = 30% more). Null for the core itself.

## Other responses

- `400`: The request is missing something or has a bad value. The message says what.
- `401`: No API key, or the key is wrong or revoked.
- `403`: The key doesn't have the scope, or isn't allowed this campaign or account.
- `429`: More than 120 requests in a minute. Wait and retry.

## Changes

- **2026-10-31** `6c1a68a75970`: 1 breaking, 5 info
  - removed `subschema #4` from the `sources/items/` request property `anyOf` list
  - added `subschema #4, subschema #5, subschema #6, subschema #7, subschema #8, subschema #9, subschema #10` to the `sources/items/` request property `anyOf` list
  - added the required property `canExpand` to the response with the `200` status
  - added the required property `groups/items/description` to the response with the `200` status
  - …2 more
- **2026-10-07** `dfe5b1c3d84f`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/skilledstars/apis/super-fans-enterprise-api/changes/exploration/map/post.md)

---

[API](https://skmtc.dev/skilledstars/apis/super-fans-enterprise-api.md) - [All operations](https://skmtc.dev/skilledstars/apis/super-fans-enterprise-api/llms.txt) - [OpenAPI document](https://skmtc.dev/skilledstars/apis/super-fans-enterprise-api/revisions/6c1a68a75970?raw)