Skip to main content
POST
/
api
/
v2
/
mentions
List mentions
curl --request POST \
  --url https://app.octolens.com/api/v2/mentions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "view": 123,
  "filters": {
    "source": [
      "reddit"
    ],
    "sentiment": [
      "positive"
    ],
    "keyword": [
      "<string>"
    ],
    "language": [
      "en"
    ],
    "tag": [
      "<string>"
    ],
    "relevance": [
      "<string>"
    ],
    "!source": [
      "reddit"
    ],
    "!sentiment": [
      "positive"
    ],
    "!keyword": [
      "<string>"
    ],
    "!language": [
      "en"
    ],
    "!tag": [
      "<string>"
    ],
    "!relevance": [
      "<string>"
    ],
    "engaged": true,
    "minXFollowers": 4503599627370495,
    "maxXFollowers": 4503599627370495,
    "startDate": "<string>",
    "endDate": "<string>"
  },
  "includeAll": false,
  "limit": 20,
  "cursor": "<string>"
}
'
{
  "data": [
    {
      "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": "en",
      "tags": [
        "competitor_mention",
        "pricing"
      ],
      "keywords": [
        {
          "id": 42,
          "keyword": "social listening"
        }
      ],
      "engaged": true
    }
  ],
  "pagination": {
    "nextCursor": "<string>"
  }
}

Documentation Index

Fetch the complete documentation index at: https://octolens.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

Authorization
string
header
required

Clerk API key. Create one in Settings → API Keys. Pass as Authorization: Bearer <key>.

Body

application/json

Filter and paginate mentions. Either provide view to reuse an existing feed's filters, or supply filters directly (or both - they merge). Body shape matches v1 /api/v1/mentions so v1 clients can reuse the same request bodies. Date ranges live inside filters.startDate / filters.endDate (ISO 8601).

view
integer

Feed/view ID to reuse as a base filter. If filters is also provided, the two are merged (view's saved filters + inline filters both apply).

Required range: x <= 9007199254740991
filters
object

Filter object. Accepts the simple flat form ({ source: ["twitter"], sentiment: ["positive"] }) or the advanced group form with AND/OR operators. Use POST /api/v2/ai/filter-wizard to generate one from natural language.

includeAll
boolean
default:false

When true, includes low-relevance mentions (internal relevanceScore = 2). Default false returns only high and medium relevance (scores 0 and 1).

limit
integer
default:20

Page size, 1-100.

Required range: 1 <= x <= 100
cursor
string

Opaque cursor from a previous response's pagination.nextCursor.

Response

200 response

Paginated list of mentions.

data
object[]
required
pagination
object
required