> ## 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.
# Mentions
> Track, triage and export the conversations that mention you.
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](/docs/cli/contract/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](/docs/cli/contract/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**
```bash theme={null}
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.
```json theme={null}
{
"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](/docs/cli/contract/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**
```bash theme={null}
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:
```json theme={null}
{
"ok": true,
"sourceId": "reddit_t3_1abc234",
"engaged": true
}
```
**Exit codes** — `0` OK · `1` UNEXPECTED · `2` USAGE. The full map is on [Exit codes](/docs/cli/contract/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**
```bash theme={null}
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.
```json theme={null}
{
"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](/docs/cli/contract/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**
```bash theme={null}
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.
```json theme={null}
{
"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](/docs/cli/contract/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**
```bash theme={null}
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.
```json theme={null}
{
"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](/docs/cli/contract/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**
```bash theme={null}
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:
```json theme={null}
{
"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](/docs/cli/contract/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**
```bash theme={null}
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.
```json theme={null}
{
"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](/docs/cli/contract/exit-codes).