Get a mention - Octolens

GET

api

mentions

{sourceId}

Get a mention

curl --request GET \
  --url https://app.octolens.com/api/v2/mentions/{sourceId} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://app.octolens.com/api/v2/mentions/{sourceId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.octolens.com/api/v2/mentions/{sourceId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://app.octolens.com/api/v2/mentions/{sourceId}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://app.octolens.com/api/v2/mentions/{sourceId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "id": 0,
  "sourceId": "reddit_t3_1abc234",
  "url": "https://reddit.com/r/example/comments/abc123/...",
  "title": "<string>",
  "body": "<string>",
  "source": "reddit",
  "timestamp": "2026-05-06 13:35:37.000",
  "author": "jane.doe",
  "authorName": "<string>",
  "authorAvatar": "<string>",
  "authorUrl": "<string>",
  "authorFollowers": 0,
  "relevance": "relevant",
  "relevanceComment": "<string>",
  "sentiment": "Neutral",
  "language": "english",
  "tags": [
    "competitor_mention",
    "pricing"
  ],
  "keywords": [
    {
      "id": 42,
      "keyword": "social listening"
    }
  ],
  "engaged": true,
  "isReply": true,
  "review": {
    "rating": 1,
    "ratingMax": 123,
    "verified": true,
    "response": "<string>",
    "responseAt": "<string>",
    "targetName": "<string>"
  },
  "relevanceScore": 123,
  "feedbackRelevant": 123,
  "imageUrl": "<string>",
  "keywordId": 123,
  "engagementMetrics": {
    "likes": 120,
    "replies": 8,
    "views": 4200
  },
  "engagementObservedAt": "<string>"
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "status": 404,
    "details": [
      "<unknown>"
    ],
    "upgradeUrl": "https://app.octolens.com/me/upgrade?src=agents",
    "upgradeCommand": "octolens upgrade"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "status": 404,
    "details": [
      "<unknown>"
    ],
    "upgradeUrl": "https://app.octolens.com/me/upgrade?src=agents",
    "upgradeCommand": "octolens upgrade"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "status": 404,
    "details": [
      "<unknown>"
    ],
    "upgradeUrl": "https://app.octolens.com/me/upgrade?src=agents",
    "upgradeCommand": "octolens upgrade"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "status": 404,
    "details": [
      "<unknown>"
    ],
    "upgradeUrl": "https://app.octolens.com/me/upgrade?src=agents",
    "upgradeCommand": "octolens upgrade"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "status": 404,
    "details": [
      "<unknown>"
    ],
    "upgradeUrl": "https://app.octolens.com/me/upgrade?src=agents",
    "upgradeCommand": "octolens upgrade"
  }
}

Authorizations

Authorization

string

header

required

Clerk API key. Create one in Settings → API Keys. Pass as Authorization: Bearer <key>. Keys carry a scope — read, write (implies read) or admin (implies write) — chosen when the key is minted. Each operation's security requirement (and its x-required-scope extension) names the minimum scope it needs; request the least-privileged key that covers the operations you call.

Path Parameters

sourceId

string

required

Stable platform-native mention id (e.g. reddit_t3_1abc234). The internal numeric id from a list row is also accepted — both resolve for recent and archived mentions. For ids that cannot ride in a URL path segment (., .., or ids equal to the sibling route names by-author/export), use GET /api/v2/mentions/by-id?sourceId=… instead.

Example:

"reddit_t3_1abc234"

Query Parameters

includeEngagementMetrics

enum<string>

Set to true to include the latest public engagement snapshot. Omit or pass false to avoid the engagement-state join.

Available options:

true,

false

Example:

"false"

Response

200 response

A single mention collected from a social platform. Canonical shape shared by list_mentions (MCP), GET /api/v2/mentions (REST), and the tRPC feed.

integer

required

Internal post id (numeric). Pass as postId to PATCH /api/v2/mentions/{sourceId}.

Required range: -9007199254740991 <= x <= 9007199254740991

sourceId

string

required

Stable composite key for the mention across the collection pipeline (e.g. reddit_t3_1abc234). Use this as the path parameter for PATCH /api/v2/mentions/{sourceId} and as the sourceId field on POST /api/v2/feedback.

Example:

"reddit_t3_1abc234"

url

string

required

Canonical URL to the original post.

Example:

"https://reddit.com/r/example/comments/abc123/..."

title

string | null

required

Post title. null for platforms that don't have titles (tweets, etc.).

body

string | null

required

Post body / content. May be empty or null for posts with no text.

source

string

required

Platform the mention was collected from. Lowercase values like reddit, twitter, linkedin. Historical rows may be uppercase.

Example:

"reddit"

timestamp

string

required

When the mention was posted. Tinybird-style datetime string (YYYY-MM-DD HH:mm:ss.SSS, UTC, no Z suffix).

Example:

"2026-05-06 13:35:37.000"

author

string | null

required

Handle/username of the mention's author. null if not captured.

Example:

"jane.doe"

authorName

string | null

required

Display name of the author, when distinct from the handle.

authorAvatar

string | null

required

URL to the author's avatar image. null if not captured.

authorUrl

string | null

required

URL to the author's profile page. null if not captured.

authorFollowers

integer | null

required

Author's follower count at collection time. null if not available.

Required range: -9007199254740991 <= x <= 9007199254740991

relevance

enum<string>

required

Relevance classification. Always one of relevant / not_relevant (unscored posts collapse to not_relevant).

Available options:

relevant,

not_relevant

Example:

"relevant"

relevanceComment

string | null

required

Free-text justification the AI produced for its relevance verdict, when available.

sentiment

enum<string> | null

required

Sentiment classification. null until the AI has scored this mention.

Available options:

Positive,

Neutral,

Negative

Example:

"Neutral"

language

string | null

required

Detected language as a full lowercase English name (english, spanish, …; undetermined when detection fails) — never an ISO 639-1 code.

Example:

"english"

tags

enum<string>[]

required

AI-assigned topic tags applied to the mention.

AI-assigned topic tag. Applied by the relevance worker during scoring. A post can carry multiple tags.

Available options:

buy_intent,

competitor_mention,

customer_testimonial,

promotional_post,

own_brand_mention,

industry_insights,

hiring,

event,

product_question,

pricing,

churn_intent,

launch_announcement,

bug_report,

user_feedback,

ai_generated

Example:

["competitor_mention", "pricing"]

keywords

object[]

required

Monitored keywords this mention matched, with id + display text.

Show child attributes

Example:

[{ "id": 42, "keyword": "social listening" }]

engaged

boolean

required

Whether a workspace member has marked this mention as engaged-with (replied, liked on-platform, etc.).

isReply

boolean

required

true for a detected reply or comment on a supported threaded platform (X, Reddit, Bluesky, or Hacker News). Legacy mentions default to false because there was no backfill.

review

object

Direct-review metadata. Omitted for ordinary social/web mentions and present for Trustpilot, Google Reviews, App Store, and Google Play reviews.

Show child attributes

relevanceScore

number | null

Raw internal relevance score (0 = high, 1 = medium, 2 = low). The public relevance field is derived from this. Optional; not all consumers populate it.

feedbackRelevant

number

User feedback on this mention's relevance: 1 for thumbs up, -1 for thumbs down, 0 for no feedback. Optional.

imageUrl

string | null

URL to a preview image attached to the post, when present.

keywordId

number

Denormalized first-matched keyword id. Convenience for callers that need a single keyword reference without scanning keywords[].

engagementMetrics

object

Latest public engagement counters for this platform. Metric names are source-specific; unavailable counters are omitted rather than reported as zero.

Show child attributes

Example:

{ "likes": 120, "replies": 8, "views": 4200 }

engagementObservedAt

string | null

UTC time at which the public engagement counters were last observed.

Get a mention

curl --request GET \
  --url https://app.octolens.com/api/v2/mentions/{sourceId} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://app.octolens.com/api/v2/mentions/{sourceId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.octolens.com/api/v2/mentions/{sourceId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://app.octolens.com/api/v2/mentions/{sourceId}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://app.octolens.com/api/v2/mentions/{sourceId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "id": 0,
  "sourceId": "reddit_t3_1abc234",
  "url": "https://reddit.com/r/example/comments/abc123/...",
  "title": "<string>",
  "body": "<string>",
  "source": "reddit",
  "timestamp": "2026-05-06 13:35:37.000",
  "author": "jane.doe",
  "authorName": "<string>",
  "authorAvatar": "<string>",
  "authorUrl": "<string>",
  "authorFollowers": 0,
  "relevance": "relevant",
  "relevanceComment": "<string>",
  "sentiment": "Neutral",
  "language": "english",
  "tags": [
    "competitor_mention",
    "pricing"
  ],
  "keywords": [
    {
      "id": 42,
      "keyword": "social listening"
    }
  ],
  "engaged": true,
  "isReply": true,
  "review": {
    "rating": 1,
    "ratingMax": 123,
    "verified": true,
    "response": "<string>",
    "responseAt": "<string>",
    "targetName": "<string>"
  },
  "relevanceScore": 123,
  "feedbackRelevant": 123,
  "imageUrl": "<string>",
  "keywordId": 123,
  "engagementMetrics": {
    "likes": 120,
    "replies": 8,
    "views": 4200
  },
  "engagementObservedAt": "<string>"
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "status": 404,
    "details": [
      "<unknown>"
    ],
    "upgradeUrl": "https://app.octolens.com/me/upgrade?src=agents",
    "upgradeCommand": "octolens upgrade"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "status": 404,
    "details": [
      "<unknown>"
    ],
    "upgradeUrl": "https://app.octolens.com/me/upgrade?src=agents",
    "upgradeCommand": "octolens upgrade"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "status": 404,
    "details": [
      "<unknown>"
    ],
    "upgradeUrl": "https://app.octolens.com/me/upgrade?src=agents",
    "upgradeCommand": "octolens upgrade"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "status": 404,
    "details": [
      "<unknown>"
    ],
    "upgradeUrl": "https://app.octolens.com/me/upgrade?src=agents",
    "upgradeCommand": "octolens upgrade"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "status": 404,
    "details": [
      "<unknown>"
    ],
    "upgradeUrl": "https://app.octolens.com/me/upgrade?src=agents",
    "upgradeCommand": "octolens upgrade"
  }
}