Audiense Insights

Creates an insights report and returns its id. Generation is asynchronous and takes 15-60 minutes: the report starts in pending status, so read it with the fetch tool until its status is finished or failed. Define the audience with exactly one of criteria or conversations. criteria uses OR-of-AND semantics: every filter in an and group must match, while any or group may match. Example: profiles in Spain whose bio mentions cooking: { "or": [{ "and": [{ "property": "location_country_code", "operator": "in", "params": ["ES"] }, { "property": "description", "operator": "contains_any", "params": ["cooking"] }] }] } Criteria values must be exact: resolve languages, interests, locations and accounts with insights-typeahead-criteria-values before creating the report, using the same network. Segmentation is optional, except on TikTok, where it is required and must be AFFINITIES or DISABLED. On X, every criteria property is accepted. On TikTok, criteria accept only gender, person, age_range, description, lang, interest, location_country_code, location_geoname_id, location_area, location_city_id. conversations accepts a network-specific query and optional time window.

insights-create-report

Takes no parameters and returns the current Audiense Insights account's email, plan and workingAs team when delegated. If the email has no valid account, it returns a statement saying so instead of account details.

whoami

Fetch the summary of one Audiense Insights report: the report detail (title, network, status, segmentation), its segments (title and size) and, embedded for the full audience and for each segment, the top values of its insights — demographics, socioeconomics, interests and industries, personality traits and online activity — plus its named entities and influencers. Use detail to configure it: "full" (default) embeds those top values, "summary" returns the report and its segment list without those values. Both include the audience the report was created from: criteria and conversations audiences with their definition, any other audience with its type only. The response includes the report_id and the segment_ids of its segments: these are the ids the other tools take. To go beyond the embedded top values — full lists, other filters, another sort order — call insights-get-report-insights, insights-get-report-entities, insights-get-report-influencers or insights-get-report-content with a selection: each entry names one report_id, with its segment_ids to read those segments or without them for the whole audience, and one call can name several audiences at once. Baseline: embedded values compare against the default baseline — the report's predefined baseline for the whole audience, the whole audience for each segment. For another comparison, call those same tools with compare_to. Network: influencers are computed on x reports only and named entities on tiktok reports only, so each network carries one of the two and never the other. Use search only when the report id is unknown; when it is known, pass it directly.

fetch

Return the content several audiences engage with — what they share and amplify — the only tool that carries it, embedded nowhere in fetch. One call reads several audiences and the response carries one result per audience, each a flat list of collections. A collection is a content type and, on x, its section: shared is what the audience posted, influential what its influencers posted. Vocabulary depends on each report's network: x has hashtags, mentions, emojis, links, domains, media, popular_posts, wordcloud across the shared, influential sections, counted by frequency; tiktok has hashtags, mentions, authors, music, topics, content_formats, no sections, as the share of the audience. A mixed-network selection keeps each result on its own vocabulary and only tiktok results carry a baseline; pass compare_to to override it — insights-get-baselines lists the predefined ones. Not paginated: pass types to choose the collections; types is required once the selection covers more than one audience. sections stays optional, filtering the x lens.

insights-get-report-content

Return the full lists of named entities several audiences talk about — the complete lists behind the top values fetch embeds — grouped by type: brands, people. Every entity arrives with the share of the audience talking about it and its distinctiveness against the baseline: sort_by percentage ranks the most talked about, count the highest absolute volume, times_more_likely the most distinctive. One call reads several audiences and the response carries one result per audience, ready to compare side by side. Each result keeps its own baseline. Pass compare_to to override it with another audience or a predefined baseline; insights-get-baselines lists the predefined ones. Not paginated: pass types to choose the groups you need; types is required once the selection covers more than one audience. Named entities exist only on tiktok reports.

insights-get-report-entities

Return the full insight distributions of one or more audiences — the complete lists behind the top values fetch embeds. Topics cover demographics, location, language, interests, behaviour (only in x reports) and psychographics (only in x reports). Every value arrives with its audience share and its distinctiveness against the baseline: sort_by percentage ranks the most common values, sort_by times_more_likely the most distinctive ones. One call reads several audiences and the response carries one result per audience, ready to compare side by side. Not paginated: pass types for the topics you need, and types is required whenever the selection covers more than one audience. Baseline: each audience compares against the default baseline. Pass compare_to to compare against another audience or a predefined baseline; insights-get-baselines lists the predefined ones.

insights-get-report-insights

Lists predefined country-and-gender baselines an audience can be compared against. Each result identifies its compatible network. Take an id from the results and pass it as compare_to to insights-get-report-insights, insights-get-report-entities, insights-get-report-influencers or insights-get-report-content. Filter by network to keep the baselines of one network only, so a tiktok report is never handed an x baseline, and by country to narrow the catalogue. Pass an id instead to read one baseline; an id that matches nothing is an error. Paginated, at most 100 baselines per page: pass the previous response's next_cursor back verbatim as cursor and stop when it is null.

insights-get-baselines

Lists the influencer categories the categories filter of insights-get-report-influencers accepts. Each category carries a label to display and the value to pass back verbatim in the filter. Takes no parameters: the catalogue is fixed.

insights-get-influencer-categories

Return the top influencers several audiences follow — the filterable lists behind the top influencers fetch embeds. One call reads several audiences, one result each: every influencer carries its profile and how much more the audience follows it than the reference (sort_by percentage, uniqueness or times_more_likely). Filters (bio keywords, entity type, followers range, categories, countries) and compare_to apply to the whole selection. Pagination follows the selection size. A single-audience selection keeps full paging: pass the previous response's next_cursor back verbatim as cursor, stop when it is null. A multi-audience selection rejects a top-level cursor and requires limit; each result returns its first page bounded by limit with its own next_cursor — to page one audience, reissue a single-audience selection carrying that next_cursor. Keep limit small (<= 25) across many audiences. Influencers exist only on x reports.

insights-get-report-influencers

List the insights reports on the account, newest-first by default. Each result carries the report id, title, network, status, creation date, segmentation type with its number of clusters and, once the report is finished, its audience size and url — enough to say which reports exist and their state without fetching any of them. Pass the report id to fetch for what a report contains. Title matching is fuzzy and case-insensitive, so an approximate or misspelled name still finds its report. Search once with the name you were given: do not retry with fragments of it. Paginated, at most 25 reports per page: pass the previous response's next_cursor back verbatim as cursor and stop when it is null.

search