Analytics

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 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

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:

{
  "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.

`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

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.

Example output

{
  "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.

`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

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:

{
  "data": [
    {
      "source": "reddit",
      "count": 203
    },
    {
      "source": "twitter",
      "count": 78
    }
  ]
}

Exit codes — 0 OK · 1 UNEXPECTED · 2 USAGE. The full map is on 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

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:

{
  "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.

`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

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.

Example output

{
  "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.

Get started

Contract

Commands

Concepts

Guides

Scripting & agents

`octolens analytics keywords`

`octolens analytics sentiment`

`octolens analytics sources`

`octolens analytics volume`

`octolens dashboard`

​octolens analytics keywords

​octolens analytics sentiment

​octolens analytics sources

​octolens analytics volume

​octolens dashboard

`octolens analytics keywords`

`octolens analytics sentiment`

`octolens analytics sources`

`octolens analytics volume`

`octolens dashboard`