> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Audiense as a data source

> Bring your Audiense Insights reports, audience segments, insights, influencers, and content analysis to Nekt.

Audiense Insights is an audience intelligence platform. It builds reports about an audience (for example, the followers of a brand or the people talking about a topic), splits it into segments with shared interests, and analyzes each audience and segment: demographics, interests, locations, languages, the influencers they follow, and the content they engage with. The Nekt connector extracts your reports and their analyses into your Catalog.

> [!NOTE]
>
> This connector is for **Audiense Insights** (audience intelligence reports). Audiense Online (e-commerce conversion tracking powered by Elevar) is a different product and is not covered by this connector.

## Before you start

The connector reads Audiense with **API credentials (Client ID and Client Secret)** created in your Audiense account. In Audiense Insights, they are under **Settings > Project Settings > Connected Accounts**.

> [!NOTE]
>
> API access depends on your Audiense plan. If you cannot find the credentials, or the connection is refused, ask your Audiense account manager to enable API access for your account.

The data the connector extracts is what these credentials can see: the intelligence reports of the account and their analyses.

## Configuring Audiense as a Source

In the [Sources](https://app.nekt.ai/sources) tab, click on the "Add source" button located on the top right of your screen. Then, select the Audiense option from the list of connectors.

Click **Next** and you'll be prompted to add your access.

### 1. Add account access

The following configurations are available:

* **Client ID**: The Client ID of your Audiense API credentials.
* **Client Secret**: The Client Secret shown next to it.
* **Report IDs**: (Advanced, optional) Read only these intelligence reports. The ID is in the address of the report when you open it in Audiense. Leave it empty to read every report of the account. A value that does not match a report the account can open makes the run fail with that value in the log.
* **Maximum influencers per audience**: (Advanced, optional) Keep only the top N influencers (by affinity) of each audience and segment. Leave it empty to load the whole ranking. When the limit cuts a ranking, the run log says so.

Once you're done, click **Next**.

### 2. Select streams

Choose which data streams you want to sync. For faster extractions, select only the streams that are relevant to your analysis.

> Tip: The stream can be found more easily by typing its name.

Select the streams and click **Next**.

### 3. Configure data streams

Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data) and the type of sync.

* **Layer**: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
* **Folder**: a folder can be created inside the selected layer to group all tables being created from this new data source.
* **Table name**: we suggest a name, but feel free to customize it. You have the option to add a **prefix** to all tables at once and make this process faster!
* **Sync Type**: every Audiense stream is FULL\_TABLE. Each run reads the current list of reports and their analyses, so a new report, a report that finished generating, or a deleted report is reflected on the next run.

Once you are done configuring, click **Next**.

### 4. Configure data source

Describe your data source for easy identification within your organization, not exceeding 140 characters.

To define your [Trigger](https://docs.nekt.com/runs/scheduling-and-triggers.md), consider how often you create reports in Audiense. A daily run is usually enough. Each run reads every report again, including the influencer ranking of every audience, so accounts with many reports take longer; use **Report IDs** or **Maximum influencers per audience** to keep runs short.

Optionally, you can define some additional settings:

* Configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource [here](https://docs.nekt.com/get-started/core-concepts/resource-control).
* An **Additional [Full Sync](https://docs.nekt.com/get-started/core-concepts/types-of-sync#additional-full-sync)** is not needed: every run is already a full read.

Once you are ready, click **Next** to finalize the setup.

### 5. Check your new source

You can view your new source on the [Sources](https://app.nekt.ai/sources) page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.

> [!WARNING]
>
> For you to be able to see it on your [Catalog](https://app.nekt.ai/catalog), you need at least one successful source run.

# Streams and Fields

## Available streams

The table below lists every stream, its **slug** (the exact identifier to pass when creating the source via API) and a short description.

| Stream | Slug | Description |
| - | - | - |
| Reports | `reports` | Intelligence reports of the account, with status, segmentation type, links, and audience size. |
| Report audiences | `report_audiences` | The full audience and each segment of every finished report, with its size. |
| Audience insights | `audience_insights` | Insights of each audience and segment: gender, age, country, city, language, interests, bio keywords, and more. |
| Audience influencers | `audience_influencers` | Influencers each audience follows, ranked by affinity. |
| Audience content | `audience_content` | Content each audience likes, shares, and is influenced by: popular posts, domains, hashtags, links, and media. Not selected by default (see below). |

Every analysis row carries `report_id` and `audience_id`. `audience_id` is the segment ID, or `full_audience` for the whole audience of the report, so you can join the analyses with `report_audiences` and `reports`. Detailed or nested data (for example the content analysis, or the complete report as returned by Audiense) is stored as JSON text, for example `json_extract_scalar(liked_content, '$.topHashtags[0].key')`.

> [!NOTE]
>
> **Reports still being generated** appear in `reports` with their status, but their audiences and analyses are loaded only on a run after Audiense finishes them. **Reports that failed** in Audiense, or that return no audience, appear only in `reports`. The run log says how many reports are in each case. If no report is visible at all, the run log asks you to check that the credentials belong to the Audiense account that has the reports. When a report that is being regenerated still lists its audiences but Audiense has no analyses for them yet, that report is skipped in the analysis tables with a warning and loaded on a later run.

> [!NOTE]
>
> **Insights of the full audience and content analysis**: Audiense provides them per audience only when the report includes them. When a report does not, those rows are not in the tables (`report_audiences` shows which analyses each audience has), and the run log warns you. The **Audience content** stream is not selected by default: it will be enabled by default once it is validated on a first live run. You can still select it.

> [!NOTE]
>
> **Errors**: if Audiense refuses one of the analyses (for example, your plan does not include influencers), that stream fails with the audience and Audiense's message in the run log, and the other streams are still extracted. If a list cannot be read consistently, or Audiense returns an unexpected response, the stream fails instead of saving a partial table. If Audiense returns the report list or an influencer ranking without pagination information, the run log asks you to confirm that nothing is missing. A report deleted while the sync runs is skipped with a warning.

## Fields by stream

> [accordion] Reports
>
> Stream name: `reports`. One row per intelligence report.
>
> **Sync Strategy:**
>
> * Full table (every run reads the current state)
> * Primary key(s): `id`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | String | Unique identifier of the intelligence report. |
> | `title` | String | Title of the report. |
> | `segmentation_type` | String | How the report splits its audience into segments (for example by interests or by affinity). |
> | `status` | String | Generation status of the report as given by Audiense (for example pending or finished). |
> | `created_at` | Datetime | When the report was created (UTC). |
> | `is_public` | Boolean | Whether the report is shared through a public link. |
> | `app_url` | String | Link to open the report in the Audiense app. |
> | `public_url` | String | Public link of the report, when it is shared. |
> | `full_audience_size` | Integer | Number of people in the report's full audience. |
> | `segments_count` | Integer | Number of segments the report found. |
> | `audience_influencers_id` | String | Identifier of the influencer analysis of the full audience, as given at report level. |
> | `errors` | String (JSON) | Errors Audiense reported while generating the report. |
> | `raw_detail` | String (JSON) | Complete report detail as returned by Audiense, including fields not split into columns. |

> [accordion] Report audiences
>
> Stream name: `report_audiences`. One row per audience of each finished report: its full audience and each segment.
>
> **Sync Strategy:**
>
> * Full table (every run reads the current state)
> * Primary key(s): `report_id`, `audience_id`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `report_id` | String | Report the audience belongs to. |
> | `audience_id` | String | Identifier of the segment, or `full_audience` for the report's full audience. |
> | `audience_type` | String | `full_audience` or `segment`. |
> | `position` | Integer | 0 for the full audience; 1, 2, and so on for the segments, in the order Audiense lists them. |
> | `title` | String | Name of the segment (empty for the full audience). |
> | `size` | Integer | Number of people in the audience. |
> | `audience_insights_id` | String | Identifier Audiense uses for the insights of this audience. |
> | `audience_influencers_id` | String | Identifier Audiense uses for the influencer analysis of this audience. |
> | `audience_content_id` | String | Identifier Audiense uses for the content analysis of this audience, when it provides one. |
> | `raw` | String (JSON) | The audience exactly as Audiense returns it in the report. |

> [accordion] Audience insights
>
> Stream name: `audience_insights`. One row per value of each insight of each audience (for example, the share of women in a segment).
>
> **Sync Strategy:**
>
> * Full table (every run reads the current state)
> * Primary key(s): `report_id`, `audience_id`, `insight_name`, `key`, `occurrence`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `report_id` | String | Report the audience belongs to. |
> | `audience_id` | String | Segment ID, or `full_audience`. |
> | `audience_type` | String | `full_audience` or `segment`. |
> | `insight_name` | String | Insight dimension as named by Audiense (for example gender, age, country, city, language, interest, bio\_keyword). |
> | `key` | String | Value of the dimension (for example `female`, `25-34`, `BR`). |
> | `value` | Number | Share of the audience with this value, as given by Audiense (usually a percentage). |
> | `raw_value` | String | The value exactly as Audiense returned it, kept when it is not a number. |
> | `position` | Integer | Order of this value within its insight, as Audiense returned it (1 = first). |
> | `occurrence` | Integer | 1 for the first entry of this key within the insight; 2, 3, and so on when Audiense returns the same key again (for example two cities with the same name). |
> | `raw` | String (JSON) | The insight entry exactly as Audiense returned it, including fields not split into columns. |

> [accordion] Audience influencers
>
> Stream name: `audience_influencers`. One row per influencer of each audience, in affinity order.
>
> **Sync Strategy:**
>
> * Full table (every run reads the current state)
> * Primary key(s): `report_id`, `audience_id`, `influencer_id`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `report_id` | String | Report the audience belongs to. |
> | `audience_id` | String | Segment ID, or `full_audience`. |
> | `audience_type` | String | `full_audience` or `segment`. |
> | `influencer_id` | String | Identifier of the influencer's social profile (X/Twitter user ID). |
> | `rank` | Integer | Position of the influencer in the audience's affinity ranking (1 = highest). |
> | `affinity` | Number | Affinity of the audience with the influencer: share of the audience that follows them (percent). |
> | `baseline_affinity` | Number | Affinity of the comparison (baseline) audience with the influencer, when Audiense provides it. |
> | `uniqueness` | Number | How distinctive the influencer is for this audience compared to the baseline, when Audiense provides it. |
> | `raw` | String (JSON) | The influencer entry exactly as Audiense returned it, including fields not split into columns. |

> [accordion] Audience content
>
> Stream name: `audience_content`. One row per audience that has a content analysis. Not selected by default.
>
> **Sync Strategy:**
>
> * Full table (every run reads the current state)
> * Primary key(s): `report_id`, `audience_id`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `report_id` | String | Report the audience belongs to. |
> | `audience_id` | String | Segment ID, or `full_audience`. |
> | `audience_type` | String | `full_audience` or `segment`. |
> | `audience_content_id` | String | Identifier of the content analysis in Audiense. |
> | `status` | String | Status of the content analysis as given by Audiense. |
> | `created_at` | Datetime | When the content analysis was created (UTC). |
> | `start_date` | Datetime | Start of the period of posts analyzed (UTC). |
> | `end_date` | Datetime | End of the period of posts analyzed (UTC). |
> | `liked_content` | String (JSON) | Content the audience likes: popular posts, top domains, emojis, hashtags, links, media, and word cloud. |
> | `shared_content` | String (JSON) | Content the audience shares, with the same breakdown. |
> | `influential_content` | String (JSON) | Content from the accounts that most influence the audience, with the same breakdown. |
> | `raw` | String (JSON) | The content analysis exactly as Audiense returned it, including fields not split into columns. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.