Get content topic share

POST

/api/v3/metrics/clicks/topic-share

curl --request POST \
  --url https://api.tryletterhead.com/api/v3/metrics/clicks/topic-share \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form api=true \
  --form from=2026-02-26 \
  --form to=2026-03-26 \
  --form 'channels[]=an-example-channel'

• Production

For each content topic, the share of your published links versus the share of clicks it earned, for the over/under-served view on the clicks dashboard — clicksShare > linksShare means a topic is under-served (readers want more of it than you publish); the reverse means it’s over-served. Links can carry more than one topic, so shares are topic-attributed and each of linksShare/clicksShare sums to 1 across all topics. Every topic in range is returned; this operation is not paginated.

This endpoint additionally requires the caller’s account to have topic-share analysis enabled, on top of the standard company API key — it returns 403 Forbidden otherwise.

v3 endpoints expect a company API key.

Authorizations

• bearerAuth

Request Body ^required

Media type multipart/form-data

object

api

required

When set to true, this endpoint will accept authorization with your API Key.

string

Example

true

from

required

Period start date (inclusive).

string

Example

2026-02-26

to

required

Period end date (inclusive), must be >= from.

string

Example

2026-03-26

channels[]

string[] | Optionally filter to a list of channels (by their slugs).

string

Example

an-example-channel

Responses

200

Get content topic share

Media type application/json

object

items

Array<object>

object

topic

string

links

Distinct published, enriched links tagged with this topic.

integer

clicks

integer

linksShare

Fraction (0–1) of all topic-attributed links that carry this topic.

number

clicksShare

Fraction (0–1) of all topic-attributed clicks earned by this topic.

number

message

string

total

Total topic count — not a page total; this operation is not paginated.

integer

Example

{
  "items": [
    {
      "topic": "Local News",
      "links": 14,
      "clicks": 320,
      "linksShare": 0.18,
      "clicksShare": 0.29
    },
    {
      "topic": "Sports",
      "links": 22,
      "clicks": 180,
      "linksShare": 0.28,
      "clicksShare": 0.16
    }
  ],
  "message": "Content topic share retrieved.",
  "total": 2
}

400

400 Validation Error — from/to missing, malformed, or from is after to.

Media type application/json

object

data

Array<string>

items

Array<object>

object

message

string

total

integer

Example

{
  "data": [
    "The from date must be on or before the to date."
  ],
  "items": [],
  "message": "Looks like the input data doesn't meet our requirements.",
  "total": 0
}

403

403 Forbidden — the caller’s account doesn’t have topic-share analysis enabled.

Media type application/json

object

data

Array<string>

items

Array<object>

object

message

string

total

integer

Example

{
  "data": [],
  "items": [],
  "message": "Content topic share is not enabled.",
  "total": 0
}