Changelog

​

October 27, 2026

​

Delete an AI Perceptions workspace’s custom channel

DELETE /workspaces/{id} can now also delete the custom channel associated with an AI Perceptions workspace in the same request. Once a workspace’s custom channel has been deleted, POST /customChannels/{channelId}/mentions answers 410 for it; the channel’s existing mentions stay searchable where they were already visible.

​

October 21, 2026

​

Narratives retirement complete

The narratives retirement announced on October 5 is now complete. Use the upgraded Landscapes product instead.

​

October 6, 2026

​

Sort mentions by an integer custom enrichment

GET /workspaces/{workspaceId}/mentions can now order its results by the value of one of your team’s integer custom enrichments.

• GET /workspaces/{workspaceId}/mentions — sort accepts custom_enrichment_id:{enrichment_id} in addition to created, published and confidence. Combine with order=asc or order=desc as before. Mentions with no value for the enrichment are returned after every mention that has one, in either order. Only integer enrichments can be sorted on; a categorical enrichment id is rejected with a 400.

Enrichment ids are listed by GET /customEnrichments. sort and order continue to be ignored when randomization_key is set.

​

October 5, 2026

​

Narratives retire on October 21, 2026

We’re retiring narratives in favor of the upgraded Landscapes product. The following parameters and fields are deprecated now and will be fully removed on Wednesday, October 21, 2026:

• GET /workspaces/{workspaceId}/narratives — the endpoint is removed.
• narratives.id — no longer accepted as a filter on GET /workspaces/{workspaceId}/mentions, GET /workspaces/{workspaceId}/analytics/timeline, or GET /workspaces/{workspaceId}/analytics/distribution. Requests that still send narratives.id get the unfiltered result.
• narrativeDetection — no longer returned on rows from GET /workspaces.
• enrichments.narratives — no longer returned on mention documents from GET /workspaces/{workspaceId}/mentions.
• sort=confidence on GET /workspaces/{workspaceId}/mentions — returns a 400.

Move to Landscapes before October 21 for the equivalent, upgraded workflow.

​

Reach and integer custom enrichments on the analytics endpoints

GET /workspaces/{workspaceId}/analytics/timeline and GET /workspaces/{workspaceId}/analytics/distribution accept a new optional metric parameter:

• mentions (default) — mention counts, exactly as before.
• reach — each time bucket or group is the summed reach of its mentions.
• custom_enrichment_sum:{enrichment_id} — each time bucket or group is the sum of an integer custom enrichment’s values, using the enrichment_id from GET /customEnrichments. Only integer enrichments provisioned for your team are accepted.

The response shape is unchanged: with a metric set, count and totalCount report the summed value of that metric instead of mention counts, and distribution percentages and ordering follow it. All filters and group_by work alongside metric.

​

September 23, 2026

​

Normalized location field across all channels

Mentions across every channel — news and social — now resolve against a normalized six-level location taxonomy: region, subregion, country, state, county, and city. state and county are United States only; mentions outside the US resolve to a country and, where the source is specific enough, a city.

• GET /locations — a new endpoint for discovering the taxonomy and the ids the location filters take.
• Filtering — the six locations.* parameters are accepted by GET /workspaces/{workspaceId}/mentions, /analytics/timeline, /analytics/distribution, and /narratives. Selecting a location automatically includes everything beneath it, so filtering on a state also returns the cities inside it.
• Grouping — the same six locations.* keys work as group_by dimensions on /analytics/timeline and /analytics/distribution.
• Mentions — items from GET /workspaces/{workspaceId}/mentions carry a location object whose ids feed straight back into the locations.* filters.

Location resolution is best effort and coverage varies by channel — strong for news, partial for social. Location is available on mentions published on or after July 1, 2026; mentions published before that date carry no normalized location. GET /workspaces/{workspaceId}/available-filters does not list location options, because the taxonomy is far too large to enumerate; use GET /locations instead.

​

Upcoming Deprecation: news-only location fields

The news-only publisher geography fields are deprecated and will be removed on December 1, 2026. Use the location taxonomy instead — it covers every channel rather than news alone.

• Query parameters publisher_geography.source_country, publisher_geography.source_region, and publisher_geography.source_sub_region → use locations.country, locations.region, and locations.subregion.
• The matching publisher_geography.* group_by values → use the equivalent locations.* values.
• The publisherGeography object on GET /workspaces/{workspaceId}/mentions → use the new location object.

​

September 15, 2026

​

Create, edit, and delete custom enrichments

You can now manage your team’s custom enrichments directly through the API, without contacting support:

• POST /customEnrichments — create an enrichment and get back the enrichment_id to push values with.
• PUT /customEnrichments/{enrichmentId} — rename an enrichment or update its option list. The list you send replaces the current one, so send the full intended list.
• DELETE /customEnrichments/{enrichmentId} — retire an enrichment you no longer need.

Enrichments can be categorical, integer, or multivalue_categorical — the new multi-value type, which holds several values per mention on one field and takes an array of strings in PUT /mentions/customEnrichments.

​

September 14, 2026

​

New multivalue_categorical custom enrichment type

Custom enrichments can now hold several values per mention on one field when they have type: "multivalue_categorical". To write to a multi-value enrichment, send the value in PUT /mentions/customEnrichments as a non-empty array of strings (up to 100 per item) rather than a single string — for example "value": ["Pricing", "Support"]. Like single-value categorical enrichments, new options auto-register on write (up to 5,000 per enrichment), and the array you send fully replaces the mention’s values for that field.

​

September 2, 2026

​

Higher daily quota for custom enrichment writes

PUT /mentions/customEnrichments now accepts 50,000 requests per day, up from 5,000. The per-minute limit (50 requests per rolling 60-second window), the midnight-UTC reset, and the rule that only 2xx responses count toward the limit are unchanged.

​

August 14, 2026

​

Workspace, folder, and channel management

The GET /workspaces endpoint has been extended with full lifecycle write operations, and folder and channel endpoints have been added.

• POST /workspaces — create a workspace with title, query, channels, and an optional folder.
• PUT /workspaces/{id} — fully replace an existing workspace (all four modifiable fields required).
• DELETE /workspaces/{id} — delete a workspace.
• GET /folders, POST /folders, PUT /folders/{id}, DELETE /folders/{id} — full CRUD for workspace folders.
• GET /channels — list the channels available to your team.

​

July 22, 2026

​

Integer Custom Enrichments

The GET /customEnrichments endpoint now returns enrichments with type: "integer" alongside the existing categorical type. Integer enrichments store numeric values and have constraints.enum always set to []. They cannot be used in filters or aggregations.

​

June 16, 2026

​

Custom Enrichments API

You can now attach your own custom enrichments to mentions in PeakMetrics with two new endpoints:

• GET /customEnrichments — list the custom enrichments provisioned for your team, including each one’s enrichment_id, name, type, and constraints.
• PUT /mentions/customEnrichments — push values for up to 100 mentions per request. Supports both standard and custom channel mentions, including historical mentions already in the platform.

Custom enrichments let you push external context about mentions into PeakMetrics, used alongside all other mention metadata in narrative analysis, summaries, and notifications, and available through the customer API and MCP server. Contact support@peakmetrics.com to set up custom enrichments!

​

May 12, 2026

​

Tweet Engagement Tracking Data on Mentions

The GET /workspaces/{workspaceId}/mentions endpoint now returns a new enrichments.engagement object.

• enrichments.engagement.history is an array of timestamped snapshots (measured_at, views, retweets, quotes, replies, favorites, bookmarks) captured on a backoff schedule during the first week after a Tweet’s published date, for Twitter / X mentions that have been opted into engagement tracking.
• For mentions that aren’t being tracked — including mentions on channels that can’t be tracked, like non-Twitter mentions — history is returned as an empty array.

See Tracking Tweet Engagement for details on how tracking is enabled and the refresh schedule.

​

May 8, 2026

​

Randomized Sampling on Mentions Endpoint

The GET /workspaces/{workspaceId}/mentions endpoint now supports an optional randomization_key query parameter. When provided, the endpoint returns a randomized sample (up to 500 mentions across all pages). Key features:

• Stable pagination via randomization_key — reuse the same key across requests to paginate through a consistent randomized pool (cached for 5 minutes)
• All standard workspace mention filters are supported, and mentions are randomly pulled from the full time range

​

May 1, 2026

​

Sentiment Fields Deprecation Now in Effect

The deprecation of sentiment fields announced on March 23 is now live. The following fields are deprecated and return 0 for all responses:

• /workspaces/{id}/mentions — enrichments.sentiment.polarity now returns 0
• /workspaces/{id}/mentions — enrichments.sentiment.version now returns 0
• /workspaces/{id}/narratives — aggregations.avgSentiment now returns 0

These fields remain in the response schema for backward compatibility but no longer contain meaningful data. Additionally for /workspaces/{id}/narratives, avgSentiment is no longer accepted as an option for the sort query param.

​

March 23, 2026

​

Upcoming Deprecation of Sentiment Fields

The generic sentiment model and its associated fields will be deprecated on May 1, 2026. After this date, the following changes take effect:

• The /workspaces/{id}/mentions endpoint will return 0 for sentiment.polarity and sentiment.version
• The /workspaces/{id}/narratives endpoint will return 0 for aggregations.avgSentiment

These fields will remain in the response schema for backward compatibility but will no longer contain meaningful data.