> ## 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.
# Analytics
> Read mention volume, sentiment and keyword trends without leaving the terminal.
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 analytics keywords`
Per-keyword mention volume (bar chart), highest first
**Flags**
| Flag | Type | Required (headless) | Description |
| ----------- | -------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--keyword` | `string` | no | Restrict the aggregation to posts matching a single tracked keyword (id or name). Note this filters the POSTS, not the output rows: `analytics keywords --keyword X` therefore returns every keyword co-mentioned on X's posts, not just X. |
| `--since` | `string` | no | Inclusive start of the window (ISO date or datetime, e.g. 2026-06-01). Must be paired with --until; omit both for the last 30 days. |
| `--until` | `string` | no | Inclusive end of the window (a bare ISO date covers the whole day; a datetime is exact). Must be paired with --since. |
**Examples**
```bash theme={null}
octolens analytics keywords
octolens analytics keywords --since 2026-06-01 --until 2026-07-01 --json
octolens analytics keywords --keyword 'next.js'
```
**Returns**
With `--json`, stdout carries one JSON document with these fields. Backed by the v2 API operation `GET /api/v2/analytics/keywords`.
| Field | Type | Description |
| ------------------ | --------- | ----------------------------------------------------------------------------------------------- |
| `data` | object\[] | One row per keyword, sorted by `count` descending. |
| `data[].keywordId` | integer | Tracked keyword id. |
| `data[].keyword` | string | Keyword text. |
| `data[].count` | integer | Mentions that matched this keyword (a mention matching several keywords counts once per match). |
With `--keyword`, the filter narrows the POSTS the aggregation runs over, so the result is a co-occurrence breakdown: every keyword appearing on the filtered keyword's posts, that keyword itself included.
Without `--json`: A terminal renders a labelled bar chart, highest first.
Example output:
```json theme={null}
{
"data": [
{
"keywordId": 42,
"keyword": "acme corp",
"count": 312
},
{
"keywordId": 57,
"keyword": "globex",
"count": 118
}
]
}
```
**Exit codes** — `0` OK · `1` UNEXPECTED · `2` USAGE. The full map is on [Exit codes](/docs/cli/contract/exit-codes).
## `octolens analytics sentiment`
Sentiment split (Positive/Neutral/Negative/unknown)
**Flags**
| Flag | Type | Required (headless) | Description |
| ----------- | -------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `--keyword` | `string` | no | Restrict the aggregation to posts matching a single tracked keyword (id or name). |
| `--since` | `string` | no | Inclusive start of the window (ISO date or datetime, e.g. 2026-06-01). Must be paired with --until; omit both for the last 30 days. |
| `--until` | `string` | no | Inclusive end of the window (a bare ISO date covers the whole day; a datetime is exact). Must be paired with --since. |
**Examples**
```bash theme={null}
octolens analytics sentiment
octolens analytics sentiment --keyword acme --json
```
**Returns**
With `--json`, stdout carries one JSON document with these fields. Backed by the v2 API operation `GET /api/v2/analytics/sentiment`.
| Field | Type | Description |
| ------------------ | -------------------------------------------------- | --------------------------------------------------------------------- |
| `data` | object\[] | One entry per sentiment bucket with a non-zero count. |
| `data[].sentiment` | enum: `Positive`, `Neutral`, `Negative`, `unknown` | Sentiment label. `unknown` covers mentions the AI has not scored yet. |
| `data[].count` | integer | Mentions with this sentiment. |
Without `--json`: A terminal renders the sentiment split as a percentage bar chart.
```json theme={null}
{
"data": [
{
"sentiment": "Positive",
"count": 96
},
{
"sentiment": "Neutral",
"count": 154
},
{
"sentiment": "Negative",
"count": 31
}
]
}
```
**Exit codes** — `0` OK · `1` UNEXPECTED · `2` USAGE. The full map is on [Exit codes](/docs/cli/contract/exit-codes).
## `octolens analytics sources`
Per-platform mention volume (bar chart), highest first
**Flags**
| Flag | Type | Required (headless) | Description |
| ----------- | -------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `--keyword` | `string` | no | Restrict the aggregation to posts matching a single tracked keyword (id or name). |
| `--since` | `string` | no | Inclusive start of the window (ISO date or datetime, e.g. 2026-06-01). Must be paired with --until; omit both for the last 30 days. |
| `--until` | `string` | no | Inclusive end of the window (a bare ISO date covers the whole day; a datetime is exact). Must be paired with --since. |
**Examples**
```bash theme={null}
octolens analytics sources
octolens analytics sources --since 2026-06-01 --until 2026-07-01 --json
```
**Returns**
With `--json`, stdout carries one JSON document with these fields. Backed by the v2 API operation `GET /api/v2/analytics/sources`.
| Field | Type | Description |
| --------------- | --------- | --------------------------------------------------- |
| `data` | object\[] | One row per platform, sorted by `count` descending. |
| `data[].source` | string | Platform slug (`reddit`, `twitter`, …). |
| `data[].count` | integer | Mentions from this source. |
Without `--json`: A terminal renders a per-source bar chart.
Example output:
```json theme={null}
{
"data": [
{
"source": "reddit",
"count": 203
},
{
"source": "twitter",
"count": 78
}
]
}
```
**Exit codes** — `0` OK · `1` UNEXPECTED · `2` USAGE. The full map is on [Exit codes](/docs/cli/contract/exit-codes).
## `octolens analytics volume`
Mention volume over time (sparkline + per-bucket counts)
**Flags**
| Flag | Type | Required (headless) | Description |
| --------------- | ------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `--granularity` | enum: `day`, `hour` | no | Bucket size. Default `day`. (default: `day`) |
| `--keyword` | `string` | no | Restrict the aggregation to posts matching a single tracked keyword (id or name). |
| `--since` | `string` | no | Inclusive start of the window (ISO date or datetime, e.g. 2026-06-01). Must be paired with --until; omit both for the last 30 days. |
| `--until` | `string` | no | Inclusive end of the window (a bare ISO date covers the whole day; a datetime is exact). Must be paired with --since. |
**Examples**
```bash theme={null}
octolens analytics volume
octolens analytics volume --granularity hour --since 2026-06-01 --until 2026-06-02
octolens analytics volume --keyword 'acme corp' --json
```
**Returns**
With `--json`, stdout carries one JSON document with these fields. Backed by the v2 API operation `GET /api/v2/analytics/volume`.
| Field | Type | Description |
| --------------- | ------------------- | -------------------------------------------------------------------------------------- |
| `granularity` | enum: `day`, `hour` | Bucket size used (echoes the request; default `day`). |
| `data` | object\[] | Buckets sorted chronologically, ascending. Empty buckets are omitted, not zero-filled. |
| `data[].bucket` | string | Bucket start: `YYYY-MM-DD` for daily granularity, ISO datetime for hourly. |
| `data[].count` | integer | Mentions that fell in this bucket. |
Without `--json`: A terminal renders the volume series as a bar chart.
Example output:
```json theme={null}
{
"granularity": "day",
"data": [
{
"bucket": "2026-07-01",
"count": 41
},
{
"bucket": "2026-07-02",
"count": 37
}
]
}
```
**Exit codes** — `0` OK · `1` UNEXPECTED · `2` USAGE. The full map is on [Exit codes](/docs/cli/contract/exit-codes).
## `octolens dashboard`
Composite KPI overview: volume trend, top keywords, sentiment split, usage vs plan
**Flags**
| Flag | Type | Required (headless) | Description |
| ----------- | -------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `--keyword` | `string` | no | Restrict the aggregation to posts matching a single tracked keyword (id or name). |
| `--since` | `string` | no | Inclusive start of the window (ISO date or datetime, e.g. 2026-06-01). Must be paired with --until; omit both for the last 30 days. |
| `--until` | `string` | no | Inclusive end of the window (a bare ISO date covers the whole day; a datetime is exact). Must be paired with --since. |
**Examples**
```bash theme={null}
octolens dashboard
octolens dashboard --since 2026-06-01 --until 2026-07-01
octolens dashboard --keyword 'acme corp' --json
```
**Returns**
With `--json`, stdout carries one JSON document with these fields. Backed by the v2 API operation `GET /api/v2/analytics/dashboard`.
| Field | Type | Description |
| ------------------------ | ------------------- | ------------------------------------------------------------------------------------------------- |
| `volume` | object | The volume series — same shape as `analytics volume` (`{granularity, data[]}`). |
| `volume.granularity` | enum: `day`, `hour` | Bucket size used (always `day` for this command). |
| `volume.data` | object\[] | Chronological buckets (`{bucket, count}`). |
| `keywords` | object\[] | Per-keyword volume rows — same rows as `analytics keywords` (`{keywordId, keyword, count}`). |
| `sentiment` | object\[] | Sentiment split rows — same rows as `analytics sentiment` (`{sentiment, count}`). |
| `usage` | object | Plan usage counters — same shape as `org usage`. |
| `usage.plan` | string \| null | Current subscription plan. The `*.limit` numbers already reflect it. |
| `usage.mentions.count` | integer | Mentions consumed in the current billing cycle. |
| `usage.mentions.limit` | integer | Mention allowance for the cycle (plan + extensions + purchased add-ons). |
| `usage.mentions.resetAt` | string \| null | When the mention counter resets (start of next cycle). `null` for plans without a reset schedule. |
| `usage.keywords.count` | integer | Live keyword count. |
| `usage.keywords.limit` | integer | Keyword allowance (plan + purchased add-ons). |
Each section carries the corresponding focused command's ROWS directly (the per-section `{data: …}` envelopes of the raw v2 response are unwrapped). When flex (usage-based) pricing is enabled for the org, the usage object additionally carries `flex` (`{enabled: true, budgetCents, used, resetAt}`); it is absent otherwise. On the **Agents plan** the analytics group — `dashboard` included — is allowlist-gated (OCT-1537) and answers the `UPGRADE_REQUIRED` wall (403 → exit `6`, with `upgradeUrl`/`upgradeCommand`) instead of data; the Agents searches meter lives in `org usage` / `billing` (see `references/admin.md`).
Without `--json`: A terminal renders the composed KPI overview: volume trend, top keywords, sentiment split, usage vs plan.
```json theme={null}
{
"volume": {
"granularity": "day",
"data": [
{
"bucket": "2026-07-01",
"count": 41
}
]
},
"keywords": [
{
"keywordId": 42,
"keyword": "acme corp",
"count": 312
}
],
"sentiment": [
{
"sentiment": "Neutral",
"count": 154
}
],
"usage": {
"plan": "Pro_v3",
"mentions": {
"count": 1240,
"limit": 5000,
"resetAt": "2026-09-01T00:00:00.000Z"
},
"keywords": {
"count": 7,
"limit": 15
}
}
}
```
**Exit codes** — `0` OK · `1` UNEXPECTED · `2` USAGE. The full map is on [Exit codes](/docs/cli/contract/exit-codes).