Skip to main content
GET
/
workspaces
/
{workspaceId}
/
narratives
Narratives
curl --request GET \
  --url https://api.peakmetrics.com/workspaces/{workspaceId}/narratives \
  --header 'Authorization: Bearer <token>'
[
  {
    "id": 2,
    "title": "<string>",
    "isFavorite": true,
    "aggregations": {
      "mentionCount": 1,
      "avgSentiment": 0,
      "relevancyScore": 50
    },
    "created": "2023-11-07T05:31:56Z",
    "summary": "<string>",
    "tags": [
      {
        "id": 123,
        "name": "<string>",
        "createdDate": "2023-11-07T05:31:56Z"
      }
    ]
  }
]

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
workspaceId
integer
required

The unique identifier for the workspace.

Required range: x >= 1

Query Parameters

​
limit
integer

The maximum number of narratives to return, default 1000.

Required range: 1 <= x <= 1000
​
offset
integer

The number of narratives to skip before returning, default 0.

Required range: x >= 0
​
sort
enum<string>

The field to sort the narratives by descending, default relevancy.

Available options:
relevancy,
mentionCount,
avgSentiment,
created,
favorite
​
since
string<date-time>
required

The minimum published date of the mentions to return.

​
to
string<date-time>
required

The maximum published date of the mentions to return.

​
channels
enum<string>[]

Filter to mentions that are part of the provided channel.

Available options:
blogsdiscussions,
bluesky,
facebook,
instagram,
news,
reddit,
redditComment,
telegram,
threads,
tiktok,
twitter,
vk,
weibo,
youtube
​
filter_expression
string

A keyword search string applied against mention content. Supports Boolean operators (AND, OR, NOT) and quoted phrases for exact matching. Field-scoped expressions are also supported (e.g., title:word or text:phrase).

This filter is applied in addition to the workspace query and any other filters. Use this for ad-hoc keyword narrowing without modifying the workspace configuration.

​
domains
string[]

Filter to mentions published on the provided domains. Multiple values are combined with OR logic.

​
authors
string[]

Filter to mentions attributed to the provided authors. Multiple values are combined with OR logic.

​
languages
string[]

Filter to mentions in the provided languages, specified as two-letter ISO 639-1 codes. Multiple values are combined with OR logic.

​
bot_ratings
enum<string>[]

Filter by bot detection confidence level. Bot detection analyzes social media accounts to identify automated or coordinated inauthentic behavior. Multiple values are combined with OR logic.

Available options:
none,
further_investigation,
very_unlikely,
unlikely,
potential,
likely,
very_likely,
almost_certain
​
smart_categories
string[]

Filter by Smart Category classification results. Smart Categories are custom AI-powered classifiers configured per workspace (e.g., sentiment models, topic classifiers, violent rhetoric detection).

Each value is a composite string in the format {enrichmentId}:{categoryKey}, where enrichmentId identifies the Smart Category model and categoryKey identifies the classification label (e.g., c0, c1, c2).

Available enrichment IDs and their category key mappings can be discovered via GET /workspaces/{workspaceId}/available-filters. Multiple values are combined with OR logic.

​
mention_type.social_media
enum<string>[]

Filter by social media post type. Use the values returned by GET /workspaces/{workspaceId}/available-filters under mention_type.social_media.options. Multiple values from the same sub-filter are combined with OR logic.

Available options:
original_posts,
reposts,
comments,
quoting_posts
​
mention_type.news
enum<string>[]

Filter to news mention type. Use the values returned by GET /workspaces/{workspaceId}/available-filters under mention_type.news.options. Multiple values are combined with OR logic.

Available options:
news
​
mention_type.podcasts
enum<string>[]

Filter to podcast mention types. Use the values returned by GET /workspaces/{workspaceId}/available-filters under mention_type.podcasts.options. Multiple values are combined with OR logic.

Available options:
podcasts
​
publisher_geography.source_country
string[]

Filter by the publisher's country of origin. Primarily applicable to news mentions. Country names should match the values returned by GET /workspaces/{workspaceId}/available-filters. Multiple values are combined with OR logic.

​
publisher_geography.source_region
enum<string>[]

Filter by the publisher's geographic region. Primarily applicable to news mentions. Multiple values are combined with OR logic.

Available options:
Africa,
Americas,
Asia,
Europe,
Oceania
​
publisher_geography.source_sub_region
enum<string>[]

Filter by the publisher's geographic subregion. Primarily applicable to news mentions. Multiple values are combined with OR logic.

Available options:
Australia and New Zealand,
Caribbean,
Central America,
Central Asia,
Eastern Africa,
Eastern Asia,
Eastern Europe,
Melanesia,
Micronesia,
Middle Africa,
Northern Africa,
Northern America,
Northern Europe,
Polynesia,
South America,
South-Eastern Asia,
Southern Africa,
Southern Asia,
Southern Europe,
Western Africa,
Western Asia,
Western Europe

Response

200 - application/json

A JSON array of narrative objects

​
id
integer

The unique identifier for the narrative.

Required range: x >= 1
​
title
string

The AI generated title for the narrative.

​
isFavorite
boolean

Favorited status of narrative for requesting user.

​
aggregations
object
​
created
string<date-time>

The date and time the narrative was created.

​
summary
string

The summary of the given narrative.

​
tags
object[]

Tags assigned by team members to the narrative.