Mentions

Flags and arguments below are the contract as the binary states it. The global flags (--json, --timeout, …) apply here too and are documented on Global flags. Error codes are a workspace-global contract, not a per-command one — the taxonomy, and how to read a code that is not in it, is on The error envelope.

`octolens mentions by-author`

List an author’s mentions on a single platform Arguments

Argument	Type	Required	Description
`AUTHOR`	`string`	optional	Author handle (or LinkedIn slug/URL for —source linkedin)

Flags

Flag	Type	Required (headless)	Description
`--all`	`boolean`	no	Drain every page (mutually exclusive with —limit)
`--limit`	`integer`	no	Return the first N mentions (across pages)
`--profile-url`	`string`	no	LinkedIn profile URL/slug (alternative to the positional author)
`--source`	`string`	yes	Platform to scope the lookup to (e.g. twitter, reddit, linkedin)

Examples

octolens mentions by-author elonmusk --source twitter
octolens mentions by-author some-slug --source linkedin --all --json

Returns With --json, stdout carries one JSON document with these fields. Backed by the v2 API operation GET /api/v2/mentions/by-author.

Field	Type	Description
`data`	object[]	The mentions of this page, newest first.
`data[].id`	integer	Internal numeric post id. `mentions update` accepts it as an alternative to the sourceId.
`data[].sourceId`	string	Stable mention key (e.g. `reddit_t3_1abc234`) — the id `mentions get`, `mentions update` and `feedback submit` take.
`data[].url`	string	Canonical URL of the original post.
`data[].title`	string \| null	Post title. `null` on platforms without titles (tweets, etc.).
`data[].body`	string \| null	Post text. May be empty or `null`.
`data[].source`	string	Platform slug, lowercase (`reddit`, `twitter`, `linkedin`, …).
`data[].timestamp`	string	When the mention was posted: UTC datetime `YYYY-MM-DD HH:mm:ss.SSS`, no `Z` suffix. Pass it back verbatim where a timestamp is required.
`data[].author`	string \| null	Author handle. `null` when not captured.
`data[].authorName`	string \| null	Author display name, when distinct from the handle.
`data[].authorAvatar`	string \| null	Author avatar image URL.
`data[].authorUrl`	string \| null	Author profile URL.
`data[].authorFollowers`	integer \| null	Author follower count at collection time.
`data[].relevance`	enum: `relevant`, `not_relevant`	AI relevance classification (unscored posts collapse to `not_relevant`).
`data[].relevanceComment`	string \| null	The AI’s justification for its relevance verdict, when available.
`data[].sentiment`	enum: `Positive`, `Neutral`, `Negative` — or null	Sentiment classification. `null` until scored.
`data[].language`	string \| null	Detected language as a full lowercase name (`english`, `spanish`, …; `undetermined` when detection fails) — never an ISO code.
`data[].tags`	string[]	AI-assigned topic tags (e.g. `competitor_mention`, `buy_intent`).
`data[].keywords`	object[]	Monitored keywords this mention matched.
`data[].keywords[].id`	integer	Tracked keyword id.
`data[].keywords[].keyword`	string	Keyword text.
`data[].engaged`	boolean	Whether a workspace member marked this mention engaged-with.
`data[].relevanceScore`	integer \| null	Raw relevance score behind `relevance` (0 high, 1 medium, 2 low). Optional — not every response carries it.
`pagination.nextCursor`	string \| null	Opaque resume cursor. `null` when the listing is complete (always `null` after `--all` drains every page).

Without --json: A terminal renders the same mention stream as mentions list. Piped (non-TTY) stdout without --json emits one tab-delimited record per mention: age, source, relevance, sentiment, author, sourceId, url, headline.

Example output

{
  "data": [
    {
      "id": 1298401,
      "sourceId": "reddit_t3_1abc234",
      "url": "https://reddit.com/r/socialmedia/comments/1abc234/best_social_listening_tools",
      "title": "Best social listening tools in 2026?",
      "body": "Looking for a tool that tracks Reddit and X mentions of our brand…",
      "source": "reddit",
      "timestamp": "2026-05-06 13:35:37.000",
      "author": "jane_doe",
      "authorName": "Jane Doe",
      "authorAvatar": "https://styles.redditmedia.com/avatars/jane_doe.png",
      "authorUrl": "https://reddit.com/user/jane_doe",
      "authorFollowers": 1240,
      "relevance": "relevant",
      "relevanceComment": "Asks for social-listening tool recommendations — a buying signal.",
      "sentiment": "Neutral",
      "language": "english",
      "tags": [
        "buy_intent"
      ],
      "keywords": [
        {
          "id": 42,
          "keyword": "social listening"
        }
      ],
      "engaged": false,
      "relevanceScore": 0
    }
  ],
  "pagination": {
    "nextCursor": null
  }
}

Exit codes — 0 OK · 1 UNEXPECTED · 2 USAGE. The full map is on Exit codes.

`octolens mentions engage`

Set (or toggle) the engaged-with flag on a mention Arguments

Argument	Type	Required	Description
`SOURCEID`	`string`	required	Mention id from a list/export row — the stable sourceId or the internal numeric id

Flags

Flag	Type	Required (headless)	Description
`--engaged`	enum: `true`, `false`	no	Target state — an idempotent absolute write. Omit to TOGGLE the current value (not idempotent: re-running it flips the flag back).

Examples

octolens mentions engage reddit_t3_1abc234 --engaged true
octolens mentions engage reddit_t3_1abc234 --engaged false --json
octolens mentions engage reddit_t3_1abc234

Returns With --json, stdout carries one JSON document with these fields. Backed by the v2 API operation PATCH /api/v2/mentions/{sourceId}.

Field	Type	Description
`ok`	boolean	Always `true` — a failed write answers the error envelope instead.
`sourceId`	string	Canonical sourceId of the mention.
`engaged`	boolean	The committed engaged-with state after this write.

Without --json: A terminal prints one confirmation line naming the new state. Example output:

{
  "ok": true,
  "sourceId": "reddit_t3_1abc234",
  "engaged": true
}

Exit codes — 0 OK · 1 UNEXPECTED · 2 USAGE. The full map is on Exit codes.

`octolens mentions export`

Export filtered mentions to a CSV/JSON file or stdout Flags

Flag	Type	Required (headless)	Description
`--author`	`string`	no	Only mentions by this author handle (requires a single —source)
`--feed`	`integer`	no	Reuse a saved feed id as the base filter
`--format`	enum: `csv`, `json`	no	Body format: csv or json. Defaults to the -o extension (.csv/.json; anything else is csv), or json when writing to stdout under —json
`--keyword`	`string`	no	Filter by keyword name or id (repeatable)
`--limit`	`integer`	no	Return only the first N mentions
`--output` (`-o`)	`string`	no	Write to this file instead of stdout (.csv/.json sets the format, any other extension is csv; .jsonl/.ndjson are refused; - and /dev/stdout mean stdout)
`--relevance`	enum: `relevant`, `all`	no	relevant (default) or all (include low-relevance mentions)
`--search`	`string`	no	Free-text search (case-insensitive substring of title, body, author handle, or author display name)
`--sentiment`	`string`	no	Filter by sentiment: positive, neutral, negative (repeatable)
`--since`	`string`	no	Only mentions on/after this ISO date. When omitted the start is unbounded — the CLI applies no default time window (the web feed’s default 7-day view does not apply here)
`--source`	`string`	no	Filter by source platform, e.g. reddit, twitter (repeatable)
`--until`	`string`	no	Only mentions on/before this ISO date (a bare date includes the whole day; a datetime is exact). Works alone: without —since it reaches back to your oldest mention, not just the last 7 days. Paired with —since it must not come BEFORE it — an inverted window exits 2 (INVALID_WINDOW) instead of returning an empty result

Examples

octolens mentions export --source reddit -o mentions.csv
octolens mentions export --feed 42 --format json > feed.json
octolens mentions export --limit 100 -o sample.csv
octolens mentions export --author elonmusk --source twitter -o elon.csv

Returns With --json, stdout carries one JSON document with these fields. Backed by the v2 API operation POST /api/v2/mentions/export.

Field	Type	Description
`data`	object[]	Exported mentions — same row shape as `mentions list`.
`data[].id`	integer	Internal numeric post id. `mentions update` accepts it as an alternative to the sourceId.
`data[].sourceId`	string	Stable mention key (e.g. `reddit_t3_1abc234`) — the id `mentions get`, `mentions update` and `feedback submit` take.
`data[].url`	string	Canonical URL of the original post.
`data[].title`	string \| null	Post title. `null` on platforms without titles (tweets, etc.).
`data[].body`	string \| null	Post text. May be empty or `null`.
`data[].source`	string	Platform slug, lowercase (`reddit`, `twitter`, `linkedin`, …).
`data[].timestamp`	string	When the mention was posted: UTC datetime `YYYY-MM-DD HH:mm:ss.SSS`, no `Z` suffix. Pass it back verbatim where a timestamp is required.
`data[].author`	string \| null	Author handle. `null` when not captured.
`data[].authorName`	string \| null	Author display name, when distinct from the handle.
`data[].authorAvatar`	string \| null	Author avatar image URL.
`data[].authorUrl`	string \| null	Author profile URL.
`data[].authorFollowers`	integer \| null	Author follower count at collection time.
`data[].relevance`	enum: `relevant`, `not_relevant`	AI relevance classification (unscored posts collapse to `not_relevant`).
`data[].relevanceComment`	string \| null	The AI’s justification for its relevance verdict, when available.
`data[].sentiment`	enum: `Positive`, `Neutral`, `Negative` — or null	Sentiment classification. `null` until scored.
`data[].language`	string \| null	Detected language as a full lowercase name (`english`, `spanish`, …; `undetermined` when detection fails) — never an ISO code.
`data[].tags`	string[]	AI-assigned topic tags (e.g. `competitor_mention`, `buy_intent`).
`data[].keywords`	object[]	Monitored keywords this mention matched.
`data[].keywords[].id`	integer	Tracked keyword id.
`data[].keywords[].keyword`	string	Keyword text.
`data[].engaged`	boolean	Whether a workspace member marked this mention engaged-with.
`data[].relevanceScore`	integer \| null	Raw relevance score behind `relevance` (0 high, 1 medium, 2 low). Optional — not every response carries it.
`total`	integer	Rows exported (capped at 50,000 per run).

This is the stdout body for --format json with no --output. With --output FILE the body goes to the file and stdout carries a one-line summary document instead — {"file", "total", "format"}, plus a warning field when the export matched nothing. --format csv emits CSV rows, not JSON. Without --json: A terminal run with --output prints a one-line summary of what was written where.

Example output

{
  "data": [
    {
      "id": 1298401,
      "sourceId": "reddit_t3_1abc234",
      "url": "https://reddit.com/r/socialmedia/comments/1abc234/best_social_listening_tools",
      "title": "Best social listening tools in 2026?",
      "body": "Looking for a tool that tracks Reddit and X mentions of our brand…",
      "source": "reddit",
      "timestamp": "2026-05-06 13:35:37.000",
      "author": "jane_doe",
      "authorName": "Jane Doe",
      "authorAvatar": "https://styles.redditmedia.com/avatars/jane_doe.png",
      "authorUrl": "https://reddit.com/user/jane_doe",
      "authorFollowers": 1240,
      "relevance": "relevant",
      "relevanceComment": "Asks for social-listening tool recommendations — a buying signal.",
      "sentiment": "Neutral",
      "language": "english",
      "tags": [
        "buy_intent"
      ],
      "keywords": [
        {
          "id": 42,
          "keyword": "social listening"
        }
      ],
      "engaged": false,
      "relevanceScore": 0
    }
  ],
  "total": 1
}

Exit codes — 0 OK · 1 UNEXPECTED · 2 USAGE. The full map is on Exit codes.

`octolens mentions get`

Get a single mention by its sourceId (or its numeric id) Arguments

Argument	Type	Required	Description
`SOURCEID`	`string`	required	Mention id from a list/export row — the stable sourceId or the internal numeric id

Examples

octolens mentions get reddit_t3_1abc234
octolens mentions get reddit_t3_1abc234 --json
octolens mentions get reddit_t3_1abc234 --web

Returns With --json, stdout carries one JSON document with these fields. Backed by the v2 API operation GET /api/v2/mentions/{sourceId}.

Field	Type	Description
`id`	integer	Internal numeric post id. `mentions update` accepts it as an alternative to the sourceId.
`sourceId`	string	Stable mention key (e.g. `reddit_t3_1abc234`) — the id `mentions get`, `mentions update` and `feedback submit` take.
`url`	string	Canonical URL of the original post.
`title`	string \| null	Post title. `null` on platforms without titles (tweets, etc.).
`body`	string \| null	Post text. May be empty or `null`.
`source`	string	Platform slug, lowercase (`reddit`, `twitter`, `linkedin`, …).
`timestamp`	string	When the mention was posted: UTC datetime `YYYY-MM-DD HH:mm:ss.SSS`, no `Z` suffix. Pass it back verbatim where a timestamp is required.
`author`	string \| null	Author handle. `null` when not captured.
`authorName`	string \| null	Author display name, when distinct from the handle.
`authorAvatar`	string \| null	Author avatar image URL.
`authorUrl`	string \| null	Author profile URL.
`authorFollowers`	integer \| null	Author follower count at collection time.
`relevance`	enum: `relevant`, `not_relevant`	AI relevance classification (unscored posts collapse to `not_relevant`).
`relevanceComment`	string \| null	The AI’s justification for its relevance verdict, when available.
`sentiment`	enum: `Positive`, `Neutral`, `Negative` — or null	Sentiment classification. `null` until scored.
`language`	string \| null	Detected language as a full lowercase name (`english`, `spanish`, …; `undetermined` when detection fails) — never an ISO code.
`tags`	string[]	AI-assigned topic tags (e.g. `competitor_mention`, `buy_intent`).
`keywords`	object[]	Monitored keywords this mention matched.
`keywords[].id`	integer	Tracked keyword id.
`keywords[].keyword`	string	Keyword text.
`engaged`	boolean	Whether a workspace member marked this mention engaged-with.
`relevanceScore`	integer \| null	Raw relevance score behind `relevance` (0 high, 1 medium, 2 low). Optional — not every response carries it.

Without --json: A terminal renders a detail panel: headline, addressing pair, classification rows, and the word-wrapped body.

Example output

{
  "id": 1298401,
  "sourceId": "reddit_t3_1abc234",
  "url": "https://reddit.com/r/socialmedia/comments/1abc234/best_social_listening_tools",
  "title": "Best social listening tools in 2026?",
  "body": "Looking for a tool that tracks Reddit and X mentions of our brand…",
  "source": "reddit",
  "timestamp": "2026-05-06 13:35:37.000",
  "author": "jane_doe",
  "authorName": "Jane Doe",
  "authorAvatar": "https://styles.redditmedia.com/avatars/jane_doe.png",
  "authorUrl": "https://reddit.com/user/jane_doe",
  "authorFollowers": 1240,
  "relevance": "relevant",
  "relevanceComment": "Asks for social-listening tool recommendations — a buying signal.",
  "sentiment": "Neutral",
  "language": "english",
  "tags": [
    "buy_intent"
  ],
  "keywords": [
    {
      "id": 42,
      "keyword": "social listening"
    }
  ],
  "engaged": false,
  "relevanceScore": 0
}

Exit codes — 0 OK · 1 UNEXPECTED · 2 USAGE. The full map is on Exit codes.

`octolens mentions list`

List mentions from your feed, filtered and paginated Flags

Flag	Type	Required (headless)	Description
`--all`	`boolean`	no	Drain every page (mutually exclusive with —limit)
`--author`	`string`	no	Only mentions by this author handle (requires a single —source)
`--feed`	`integer`	no	Reuse a saved feed id as the base filter
`--keyword`	`string`	no	Filter by keyword name or id (repeatable)
`--limit`	`integer`	no	Return only the first N mentions
`--relevance`	enum: `relevant`, `all`	no	relevant (default) or all (include low-relevance mentions)
`--search`	`string`	no	Free-text search (case-insensitive substring of title, body, author handle, or author display name)
`--sentiment`	`string`	no	Filter by sentiment: positive, neutral, negative (repeatable)
`--since`	`string`	no	Only mentions on/after this ISO date. When omitted the start is unbounded — the CLI applies no default time window (the web feed’s default 7-day view does not apply here)
`--source`	`string`	no	Filter by source platform, e.g. reddit, twitter (repeatable)
`--until`	`string`	no	Only mentions on/before this ISO date (a bare date includes the whole day; a datetime is exact). Works alone: without —since it reaches back to your oldest mention, not just the last 7 days. Paired with —since it must not come BEFORE it — an inverted window exits 2 (INVALID_WINDOW) instead of returning an empty result

Examples

octolens mentions list
octolens mentions list --source reddit --sentiment negative
octolens mentions list --keyword 'social listening' --since 2026-06-01
octolens mentions list --search 'pricing page' --source reddit
octolens mentions list --feed 42 --all --json
octolens mentions list --author elonmusk --source twitter

Returns With --json, stdout carries one JSON document with these fields. Backed by the v2 API operation POST /api/v2/mentions.

Field	Type	Description
`data`	object[]	The mentions of this page, newest first.
`data[].id`	integer	Internal numeric post id. `mentions update` accepts it as an alternative to the sourceId.
`data[].sourceId`	string	Stable mention key (e.g. `reddit_t3_1abc234`) — the id `mentions get`, `mentions update` and `feedback submit` take.
`data[].url`	string	Canonical URL of the original post.
`data[].title`	string \| null	Post title. `null` on platforms without titles (tweets, etc.).
`data[].body`	string \| null	Post text. May be empty or `null`.
`data[].source`	string	Platform slug, lowercase (`reddit`, `twitter`, `linkedin`, …).
`data[].timestamp`	string	When the mention was posted: UTC datetime `YYYY-MM-DD HH:mm:ss.SSS`, no `Z` suffix. Pass it back verbatim where a timestamp is required.
`data[].author`	string \| null	Author handle. `null` when not captured.
`data[].authorName`	string \| null	Author display name, when distinct from the handle.
`data[].authorAvatar`	string \| null	Author avatar image URL.
`data[].authorUrl`	string \| null	Author profile URL.
`data[].authorFollowers`	integer \| null	Author follower count at collection time.
`data[].relevance`	enum: `relevant`, `not_relevant`	AI relevance classification (unscored posts collapse to `not_relevant`).
`data[].relevanceComment`	string \| null	The AI’s justification for its relevance verdict, when available.
`data[].sentiment`	enum: `Positive`, `Neutral`, `Negative` — or null	Sentiment classification. `null` until scored.
`data[].language`	string \| null	Detected language as a full lowercase name (`english`, `spanish`, …; `undetermined` when detection fails) — never an ISO code.
`data[].tags`	string[]	AI-assigned topic tags (e.g. `competitor_mention`, `buy_intent`).
`data[].keywords`	object[]	Monitored keywords this mention matched.
`data[].keywords[].id`	integer	Tracked keyword id.
`data[].keywords[].keyword`	string	Keyword text.
`data[].engaged`	boolean	Whether a workspace member marked this mention engaged-with.
`data[].relevanceScore`	integer \| null	Raw relevance score behind `relevance` (0 high, 1 medium, 2 low). Optional — not every response carries it.
`pagination.nextCursor`	string \| null	Opaque resume cursor. `null` when the listing is complete (always `null` after `--all` drains every page).

--limit/--all page client-side, so the emitted data already holds every requested row. Without --json: A terminal renders a readable mention stream (headline, source, relative date, sentiment). Piped (non-TTY) stdout without --json emits one tab-delimited record per mention: age, source, relevance, sentiment, author, sourceId, url, headline.

Example output

{
  "data": [
    {
      "id": 1298401,
      "sourceId": "reddit_t3_1abc234",
      "url": "https://reddit.com/r/socialmedia/comments/1abc234/best_social_listening_tools",
      "title": "Best social listening tools in 2026?",
      "body": "Looking for a tool that tracks Reddit and X mentions of our brand…",
      "source": "reddit",
      "timestamp": "2026-05-06 13:35:37.000",
      "author": "jane_doe",
      "authorName": "Jane Doe",
      "authorAvatar": "https://styles.redditmedia.com/avatars/jane_doe.png",
      "authorUrl": "https://reddit.com/user/jane_doe",
      "authorFollowers": 1240,
      "relevance": "relevant",
      "relevanceComment": "Asks for social-listening tool recommendations — a buying signal.",
      "sentiment": "Neutral",
      "language": "english",
      "tags": [
        "buy_intent"
      ],
      "keywords": [
        {
          "id": 42,
          "keyword": "social listening"
        }
      ],
      "engaged": false,
      "relevanceScore": 0
    }
  ],
  "pagination": {
    "nextCursor": "eyJvZmZzZXQiOjIwfQ=="
  }
}

Exit codes — 0 OK · 1 UNEXPECTED · 2 USAGE. The full map is on Exit codes.

`octolens mentions update`

Override a mention’s relevance and/or sentiment (triage) Arguments

Argument	Type	Required	Description
`SOURCEID`	`string`	required	Mention id from a list/export row — the stable sourceId or the internal numeric id

Flags

Flag	Type	Required (headless)	Description
`--relevance`	`string`	one of (headless)	Set relevance: relevant, not_relevant, high, medium, low, clear
`--sentiment`	`string`	one of (headless)	Set sentiment: Positive, Neutral, Negative

Examples

octolens mentions update reddit_t3_1abc234 --relevance not_relevant
octolens mentions update reddit_t3_1abc234 --sentiment Negative --json

Returns With --json, stdout carries one JSON document with these fields. Backed by the v2 API operation PATCH /api/v2/mentions/{sourceId}.

Field	Type	Description
`ok`	boolean	Always `true` — a failed update answers the error envelope instead.
`sourceId`	string	Canonical sourceId of the updated mention (even when the command was invoked with the numeric id).
`relevance`	enum: `relevant`, `not_relevant`	Committed relevance classification. Present only when `--relevance` was passed.
`relevanceScore`	integer \| null	Committed raw score (0 high, 1 medium, 2 low). Present only when `--relevance` was passed.
`sentiment`	enum: `Positive`, `Neutral`, `Negative` — or null	Committed sentiment. Present only when `--sentiment` was passed.

The payload is the COMMITTED state read back from the update, not an echo of the flags — --relevance clear reports whatever classification the AI verdict restored. Without --json: A terminal prints one confirmation line with the same committed values. Example output:

{
  "ok": true,
  "sourceId": "reddit_t3_1abc234",
  "relevance": "relevant",
  "relevanceScore": 0,
  "sentiment": "Positive"
}

Exit codes — 0 OK · 1 UNEXPECTED · 2 USAGE · 8 CANCELLED. The full map is on Exit codes.

`octolens search`

Search any phrase across your enabled platforms — one-time, AI-scored (results never join your mentions feed) Arguments

Argument	Type	Required	Description
`QUERY`	`string`	required	The phrase to search for (quote multi-word phrases)

Flags

Flag	Type	Required (headless)	Description
`--days`	enum: `1`, `7`, `30`	no	How far back to search: 1, 7, or 30 days (default: `7`)
`--max-results`	`integer`	no	Result budget: how many candidates are fetched and AI-scored (1-500, default 100). Scored results are what consume mention quota
`--min-relevance`	enum: `high`, `medium`, `low`	no	Hide results the AI scored below this bar (display filter only; default medium)
`--source`	`string`	no	Platform(s) to search — repeatable or comma-separated (e.g. reddit,twitter,hackernews). Default: every source enabled for your workspace

Examples

octolens search "your brand" --days 7 --json
octolens search "linux foundation" --days 30 --source reddit,hackernews
octolens search "acme corp" --min-relevance high --max-results 50

Returns With --json, stdout carries one JSON document with these fields. Backed by the v2 API operation POST /api/v2/search.

Field	Type	Description
`searchId`	string	Stable id of this search (`srch_…`).
`status`	enum: `completed`	Always `completed` — the command transparently polls an async (202) search to its terminal state before printing; a failed or quota-exhausted search answers the error envelope instead.
`query`	string	The phrase that was searched.
`timeWindow`	enum: `1d`, `7d`, `30d`	The window that was searched — what `--days 1\|7\|30` maps onto.
`sources`	string[]	The platform slugs that were searched (after workspace/plan resolution).
`startedAt`	string	When the search started, ISO 8601.
`completedAt`	string	When the search completed, ISO 8601.
`stats`	object	Per-stage funnel counts for the search.
`stats.rawMatches`	integer	Candidates fetched across all sources.
`stats.afterDedup`	integer	Candidates left after de-duplication.
`stats.afterRelevance`	integer	Results left after AI relevance scoring and the `--min-relevance` display bar.
`stats.mentionsConsumed`	integer	Mentions this search consumed from the monthly quota (results already in the workspace are free).
`stats.perSource`	object	Raw candidate count per source slug.
`stats.skippedSources`	object	Sources that could not be searched, mapped to the human-readable reason. Absent when nothing was skipped.
`mentions`	object[]	The results, ranked by relevance — the same row shape as `mentions list`, plus `alreadyInWorkspace`.
`mentions[].id`	integer	Internal numeric post id. `mentions update` accepts it as an alternative to the sourceId.
`mentions[].sourceId`	string	Stable mention key (e.g. `reddit_t3_1abc234`) — the id `mentions get`, `mentions update` and `feedback submit` take.
`mentions[].url`	string	Canonical URL of the original post.
`mentions[].title`	string \| null	Post title. `null` on platforms without titles (tweets, etc.).
`mentions[].body`	string \| null	Post text. May be empty or `null`.
`mentions[].source`	string	Platform slug, lowercase (`reddit`, `twitter`, `linkedin`, …).
`mentions[].timestamp`	string	When the mention was posted: UTC datetime `YYYY-MM-DD HH:mm:ss.SSS`, no `Z` suffix. Pass it back verbatim where a timestamp is required.
`mentions[].author`	string \| null	Author handle. `null` when not captured.
`mentions[].authorName`	string \| null	Author display name, when distinct from the handle.
`mentions[].authorAvatar`	string \| null	Author avatar image URL.
`mentions[].authorUrl`	string \| null	Author profile URL.
`mentions[].authorFollowers`	integer \| null	Author follower count at collection time.
`mentions[].relevance`	enum: `relevant`, `not_relevant`	AI relevance classification (unscored posts collapse to `not_relevant`).
`mentions[].relevanceComment`	string \| null	The AI’s justification for its relevance verdict, when available.
`mentions[].sentiment`	enum: `Positive`, `Neutral`, `Negative` — or null	Sentiment classification. `null` until scored.
`mentions[].language`	string \| null	Detected language of a fresh search result as a lowercase ISO 639-1 code (`en`, `es`, …) — unlike the mentions feed, which uses full names. A row flagged `alreadyInWorkspace` keeps the workspace’s stored full-name value (`english`).
`mentions[].tags`	string[]	AI-assigned topic tags (e.g. `competitor_mention`, `buy_intent`).
`mentions[].keywords`	object[]	Monitored keywords this mention matched.
`mentions[].keywords[].id`	integer	Tracked keyword id.
`mentions[].keywords[].keyword`	string	Keyword text.
`mentions[].engaged`	boolean	Whether a workspace member marked this mention engaged-with.
`mentions[].relevanceScore`	integer \| null	Raw relevance score behind `relevance` (0 high, 1 medium, 2 low). Optional — not every response carries it.
`mentions[].alreadyInWorkspace`	boolean	`true` when the workspace’s monitored keywords had already collected this result — flagged results do not count against the monthly mention quota. Optional (absent means new).

This is the v2 completed-search envelope, byte-identical whether the search finished synchronously or the CLI polled an async (202) search to completion. The low-quota warning (Agents plan, below threshold) rides on STDERR — as one JSON object under --json — never inside this document. Without --json: A terminal renders each result in the mentions list stream layout, ranked by relevance, then a dim stats footer (132 raw matches → 41 after relevance · 38 mentions consumed · 3 sources searched). Piped stdout emits the same tab-delimited record per result as mentions list, and nothing else.

Example output

{
  "searchId": "srch_2h9dK3mQxYz",
  "status": "completed",
  "query": "linux foundation",
  "timeWindow": "7d",
  "sources": [
    "reddit",
    "twitter",
    "hackernews"
  ],
  "startedAt": "2026-08-12T09:00:00.000Z",
  "completedAt": "2026-08-12T09:00:19.000Z",
  "stats": {
    "rawMatches": 132,
    "afterDedup": 97,
    "afterRelevance": 41,
    "mentionsConsumed": 38,
    "perSource": {
      "reddit": 61,
      "twitter": 48,
      "hackernews": 23
    },
    "skippedSources": {
      "linkedin": "requires the LinkedIn add-on"
    }
  },
  "mentions": [
    {
      "id": 1298401,
      "sourceId": "reddit_t3_1abc234",
      "url": "https://reddit.com/r/socialmedia/comments/1abc234/best_social_listening_tools",
      "title": "Best social listening tools in 2026?",
      "body": "Looking for a tool that tracks Reddit and X mentions of our brand…",
      "source": "reddit",
      "timestamp": "2026-05-06 13:35:37.000",
      "author": "jane_doe",
      "authorName": "Jane Doe",
      "authorAvatar": "https://styles.redditmedia.com/avatars/jane_doe.png",
      "authorUrl": "https://reddit.com/user/jane_doe",
      "authorFollowers": 1240,
      "relevance": "relevant",
      "relevanceComment": "Asks for social-listening tool recommendations — a buying signal.",
      "sentiment": "Neutral",
      "language": "en",
      "tags": [
        "buy_intent"
      ],
      "keywords": [
        {
          "id": 42,
          "keyword": "social listening"
        }
      ],
      "engaged": false,
      "relevanceScore": 0,
      "alreadyInWorkspace": false
    }
  ]
}

Exit codes — 0 OK · 1 UNEXPECTED · 2 USAGE. The full map is on Exit codes.

Get started

Contract

Commands

Concepts

Guides

Scripting & agents

`octolens mentions by-author`

`octolens mentions engage`

`octolens mentions export`

`octolens mentions get`

`octolens mentions list`

`octolens mentions update`

`octolens search`

​octolens mentions by-author

​octolens mentions engage

​octolens mentions export

​octolens mentions get

​octolens mentions list

​octolens mentions update

​octolens search

`octolens mentions by-author`

`octolens mentions engage`

`octolens mentions export`

`octolens mentions get`

`octolens mentions list`

`octolens mentions update`

`octolens search`