Introduction - PeakMetrics

Welcome to the PeakMetrics API

The PeakMetrics API provides programmatic access to media intelligence data, including workspaces and mentions across multiple channels. Base URL: https://api.peakmetrics.com API Version: 2.0.0

Core Concepts

Workspaces

A Workspace defines a segment of the media ecosystem you’re interested in analyzing and is comprised of all related mentions. Typical workspaces represent:

A company (e.g., “Home Depot”)
A key executive
An industry or topic (e.g., “Artificial Intelligence”)
A group of sources or geographic region

Mentions

A Mention is a piece of content written by an author, promoted by a publisher, and released on a domain as part of a channel. Mentions are the fundamental data units in PeakMetrics.

Channels

PeakMetrics monitors content across multiple channels:

News
Social media (Twitter, Facebook, Instagram, Threads, Bluesky)
Video platforms (YouTube, TikTok)
Discussion platforms (Reddit, Telegram)
International platforms (VK, Weibo)
Blogs and discussions

Authentication

All API endpoints (except /access/token) require authentication using Bearer tokens with JWT format.

Getting an Access Token

First, obtain an access token using your credentials:

POST /access/token

{
  "username": "your_username",
  "password": "your_password",
  "client_id": "your_client_id"
}

The response includes:

{
  "Token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "ExpiresIn": 3600
}

Using the Token

Include the token in the Authorization header for all subsequent requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Errors

The API uses standard HTTP status codes. A 2xx status means the request succeeded; any other status means it did not, and the body usually describes the problem in a JSON error field. Check the status code, not the body, to decide whether a request succeeded.

Status	Meaning
`400`	The request is invalid: a missing or malformed parameter or body field.
`401`	The access token is missing, invalid, or expired. On `POST /access/token`, the credentials are incorrect.
`403`	You are authenticated but not allowed to do this, for example a workspace your account cannot access.
`404`	The resource does not exist.
`409`	The request conflicts with an existing resource, for example a duplicate name.
`413`	The request body is too large.
`429`	A rate limit or quota was exceeded. Wait before retrying.
`500`	An unexpected server error. Retry with backoff.

Each endpoint’s reference page lists the error statuses specific to it. 429 and 500 can occur on any endpoint and are not repeated on every page.

Rate Limits & Pagination

Workspaces: No explicit limit
Mentions: Maximum 50 per request (use limit and offset for pagination)

Quick Start

Authenticate and get an access token POST /access/token
Retrieve your workspaces GET /workspaces
For a workspace, get its available filters GET /workspace/{workspaceId}/available-filters
Query analytics or mentions with filters applied

​Welcome to the PeakMetrics API

​Core Concepts

​Workspaces

​Mentions

​Channels

​Authentication

​Getting an Access Token

​Using the Token

​Errors

​Rate Limits & Pagination

​Quick Start