REST API / Collections

`mentions`

CollectionLarge: filter on indexed fields

Mentions from accessible projects. Filter subject_kind = OWN for own-brand mentions; is_own_domain describes the source URL owner. Public snippets fall back to matched excerpts. Outside-surface text and URLs are masked before projection; Perception counting fields require every permitted project to have counting enabled.

Max rows per query: 100
Default order: sort_at desc
Required filter: one of project_id, id
Max offset: 2000
Cursor paging: by id

Use read report_* for dashboard headline metrics and anchored comparison windows.

Fields

Field	Type	Description	Filter	Sort
`id` indexed	`string`	Unique row ID.	✓	✓
`project_id` indexed	`string`	Project ID from projects.	✓	–
`pipeline` indexed	`string`	Ingestion pipeline. `AEO` `BM` `SIGNAL`	✓	✓
`channel` indexed	`string`	Source channel. `CHATGPT` `GOOGLE_AIO` `WEB_SERP` `REDDIT` `XCOM` `LINKEDIN` `FACEBOOK` `QUORA` `STACKOVERFLOW` `GITHUB` `INSTAGRAM` `YOUTUBE` `TIKTOK` `FORUM`	✓	✓
`subject_kind` indexed	`string`	Tracked subject kind. `OWN` `COMPETITOR` `TOPIC`	✓	✓
`subject_label` indexed	`string`	Canonical tracked subject.	✓	✓
`ai_answer_id` nullable indexed	`string`	Related AI answer ID.	✓	✓
`url` nullable redacted	`string`	Public source URL, or null when it identifies a personal account.	–	–
`domain` nullable indexed	`string`	Source domain.	✓	✓
`title` nullable redacted	`string`	Public title.	–	–
`snippet` nullable redacted	`string`	Public excerpt: stored snippet or matched excerpt, masked for LinkedIn or deleted sources.	–	–
`matched_keywords`	`string[]`	Matched tracked keywords.	–	–
`category` nullable	`string`	Source category.	–	–
`page_type` nullable	`string`	Page type.	–	–
`language` nullable indexed	`string`	Detected language.	✓	✓
`published_at` nullable indexed	`datetime`	Source publication time.	✓	✓
`discovered_at` indexed	`datetime`	Ingestion time.	✓	✓
`sort_at` indexed	`datetime`	Source time or ingestion time when publication is unknown.	✓	✓
`tags` redacted	`string[]`	Visible content and custom tag slugs.	–	–
`starred`	`boolean`	Whether starred.	–	–
`seen_at` nullable	`datetime`	When last marked seen.	–	–
`archived_at` nullable indexed	`datetime`	When archived.	✓	✓
`is_own_domain`	`boolean`	Whether owned by the project brand.	–	–
`is_competitor_domain`	`boolean`	Owned by a tracked competitor	–	–
`opportunity_score` nullable indexed	`number`	Opportunity score.	✓	✓
`sentiment_score` nullable	`integer`	Sentiment from 0 to 100.	–	–
`sentiment_label` nullable indexed	`string`	Sentiment category. `NEGATIVE` `NEUTRAL` `POSITIVE`	✓	✓
`sentiment_theme` nullable indexed	`string`	Sentiment theme.	✓	✓
`engagement_score` nullable	`integer`	Platform score.	–	–
`engagement_comments` nullable	`integer`	Comment count.	–	–
`engagement_views` nullable	`integer`	View count.	–	–
`posted_by_brand` nullable Requires Perception	`string`	Publishing brand. Requires Perception counting.	–	–
`community` nullable indexed Requires Perception	`string`	Community, or null when it names a person (such as a Reddit profile). Requires Perception counting.	✓	✓
`perception_opinion` nullable Requires Perception	`boolean`	Whether a statement about the subject was extracted. Requires Perception counting.	–	–
`redacted_fields`	`json`	Populated fields hidden by privacy policy, with a reason. Empty means no populated field was redacted.	–	–

Examples

Example

SELECT id, project_id, pipeline, channel, subject_kind
FROM mentions
WHERE project_id = $1
ORDER BY sort_at DESC
LIMIT 25

Calling it

MCP

Tool call

query({"sql":"SELECT id, project_id, pipeline, channel, subject_kind FROM mentions WHERE project_id = $1 ORDER BY sort_at DESC LIMIT 25","params":["<value 1>"]})

REST

curl

curl -X POST "https://app.sensorhub.ai/api/v1/query" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "sql": "SELECT id, project_id, pipeline, channel, subject_kind FROM mentions WHERE project_id = $1 ORDER BY sort_at DESC LIMIT 25",
  "params": [
    "<value 1>"
  ]
}
JSON

Row JSON Schema

json

{
  "type": "object",
  "description": "Mentions from accessible projects. Filter subject_kind = OWN for own-brand mentions; is_own_domain describes the source URL owner. Public snippets fall back to matched excerpts. Outside-surface text and URLs are masked before projection; Perception counting fields require every permitted project to have counting enabled.",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique row ID.",
      "x-sensorhub-indexed": true,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": true,
      "x-sensorhub-sortable": true
    },
    "project_id": {
      "type": "string",
      "description": "Project ID from projects.",
      "x-sensorhub-indexed": true,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": true,
      "x-sensorhub-sortable": false
    },
    "pipeline": {
      "type": "string",
      "description": "Ingestion pipeline.",
      "enum": [
        "AEO",
        "BM",
        "SIGNAL"
      ],
      "x-sensorhub-filter-operators": [
        "=",
        "!=",
        "<>",
        "IN",
        "NOT IN",
        "IS NULL",
        "IS NOT NULL"
      ],
      "x-sensorhub-indexed": true,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": true,
      "x-sensorhub-sortable": true
    },
    "channel": {
      "type": "string",
      "description": "Source channel.",
      "enum": [
        "CHATGPT",
        "GOOGLE_AIO",
        "WEB_SERP",
        "REDDIT",
        "XCOM",
        "LINKEDIN",
        "FACEBOOK",
        "QUORA",
        "STACKOVERFLOW",
        "GITHUB",
        "INSTAGRAM",
        "YOUTUBE",
        "TIKTOK",
        "FORUM"
      ],
      "x-sensorhub-filter-operators": [
        "=",
        "!=",
        "<>",
        "IN",
        "NOT IN",
        "IS NULL",
        "IS NOT NULL"
      ],
      "x-sensorhub-indexed": true,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": true,
      "x-sensorhub-sortable": true
    },
    "subject_kind": {
      "type": "string",
      "description": "Tracked subject kind.",
      "enum": [
        "OWN",
        "COMPETITOR",
        "TOPIC"
      ],
      "x-sensorhub-filter-operators": [
        "=",
        "!=",
        "<>",
        "IN",
        "NOT IN",
        "IS NULL",
        "IS NOT NULL"
      ],
      "x-sensorhub-indexed": true,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": true,
      "x-sensorhub-sortable": true
    },
    "subject_label": {
      "type": "string",
      "description": "Canonical tracked subject.",
      "x-sensorhub-indexed": true,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": true,
      "x-sensorhub-sortable": true
    },
    "ai_answer_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Related AI answer ID.",
      "x-sensorhub-indexed": true,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": true,
      "x-sensorhub-sortable": true
    },
    "url": {
      "type": [
        "string",
        "null"
      ],
      "description": "Public source URL, or null when it identifies a personal account.",
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": false,
      "x-sensorhub-filterable": false,
      "x-sensorhub-sortable": false
    },
    "domain": {
      "type": [
        "string",
        "null"
      ],
      "description": "Source domain.",
      "x-sensorhub-indexed": true,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": true,
      "x-sensorhub-sortable": true
    },
    "title": {
      "type": [
        "string",
        "null"
      ],
      "description": "Public title.",
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": false,
      "x-sensorhub-filterable": false,
      "x-sensorhub-sortable": false
    },
    "snippet": {
      "type": [
        "string",
        "null"
      ],
      "description": "Public excerpt: stored snippet or matched excerpt, masked for LinkedIn or deleted sources.",
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": false,
      "x-sensorhub-filterable": false,
      "x-sensorhub-sortable": false
    },
    "matched_keywords": {
      "type": "array",
      "description": "Matched tracked keywords.",
      "items": {
        "type": "string"
      },
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": false,
      "x-sensorhub-filterable": false,
      "x-sensorhub-sortable": false
    },
    "category": {
      "type": [
        "string",
        "null"
      ],
      "description": "Source category.",
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": false,
      "x-sensorhub-sortable": false
    },
    "page_type": {
      "type": [
        "string",
        "null"
      ],
      "description": "Page type.",
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": false,
      "x-sensorhub-sortable": false
    },
    "language": {
      "type": [
        "string",
        "null"
      ],
      "description": "Detected language.",
      "x-sensorhub-indexed": true,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": true,
      "x-sensorhub-sortable": true
    },
    "published_at": {
      "type": [
        "string",
        "null"
      ],
      "description": "Source publication time.",
      "format": "date-time",
      "x-sensorhub-indexed": true,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": true,
      "x-sensorhub-sortable": true
    },
    "discovered_at": {
      "type": "string",
      "description": "Ingestion time.",
      "format": "date-time",
      "x-sensorhub-indexed": true,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": true,
      "x-sensorhub-sortable": true
    },
    "sort_at": {
      "type": "string",
      "description": "Source time or ingestion time when publication is unknown.",
      "format": "date-time",
      "x-sensorhub-indexed": true,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": true,
      "x-sensorhub-sortable": true
    },
    "tags": {
      "type": "array",
      "description": "Visible content and custom tag slugs.",
      "items": {
        "type": "string"
      },
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": false,
      "x-sensorhub-filterable": false,
      "x-sensorhub-sortable": false
    },
    "starred": {
      "type": "boolean",
      "description": "Whether starred.",
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": false,
      "x-sensorhub-sortable": false
    },
    "seen_at": {
      "type": [
        "string",
        "null"
      ],
      "description": "When last marked seen.",
      "format": "date-time",
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": false,
      "x-sensorhub-sortable": false
    },
    "archived_at": {
      "type": [
        "string",
        "null"
      ],
      "description": "When archived.",
      "format": "date-time",
      "x-sensorhub-indexed": true,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": true,
      "x-sensorhub-sortable": true
    },
    "is_own_domain": {
      "type": "boolean",
      "description": "Whether owned by the project brand.",
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": false,
      "x-sensorhub-sortable": false
    },
    "is_competitor_domain": {
      "type": "boolean",
      "description": "Owned by a tracked competitor",
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": false,
      "x-sensorhub-sortable": false
    },
    "opportunity_score": {
      "type": [
        "number",
        "null"
      ],
      "description": "Opportunity score.",
      "x-sensorhub-indexed": true,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": true,
      "x-sensorhub-sortable": true
    },
    "sentiment_score": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Sentiment from 0 to 100.",
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": false,
      "x-sensorhub-sortable": false
    },
    "sentiment_label": {
      "type": [
        "string",
        "null"
      ],
      "description": "Sentiment category.",
      "enum": [
        "NEGATIVE",
        "NEUTRAL",
        "POSITIVE",
        null
      ],
      "x-sensorhub-filter-operators": [
        "=",
        "!=",
        "<>",
        "IN",
        "NOT IN",
        "IS NULL",
        "IS NOT NULL"
      ],
      "x-sensorhub-indexed": true,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": true,
      "x-sensorhub-sortable": true
    },
    "sentiment_theme": {
      "type": [
        "string",
        "null"
      ],
      "description": "Sentiment theme.",
      "x-sensorhub-indexed": true,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": true,
      "x-sensorhub-sortable": true
    },
    "engagement_score": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Platform score.",
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": false,
      "x-sensorhub-sortable": false
    },
    "engagement_comments": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Comment count.",
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": false,
      "x-sensorhub-sortable": false
    },
    "engagement_views": {
      "type": [
        "integer",
        "null"
      ],
      "description": "View count.",
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": false,
      "x-sensorhub-sortable": false
    },
    "posted_by_brand": {
      "type": [
        "string",
        "null"
      ],
      "description": "Publishing brand. Requires Perception counting.",
      "x-sensorhub-availability": "Requires Perception",
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": false,
      "x-sensorhub-sortable": false
    },
    "community": {
      "type": [
        "string",
        "null"
      ],
      "description": "Community, or null when it names a person (such as a Reddit profile). Requires Perception counting.",
      "x-sensorhub-availability": "Requires Perception",
      "x-sensorhub-indexed": true,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": true,
      "x-sensorhub-sortable": true
    },
    "perception_opinion": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "Whether a statement about the subject was extracted. Requires Perception counting.",
      "x-sensorhub-availability": "Requires Perception",
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": false,
      "x-sensorhub-sortable": false
    },
    "redacted_fields": {
      "description": "Populated fields hidden by privacy policy, with a reason. Empty means no populated field was redacted.",
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": false,
      "x-sensorhub-filterable": false,
      "x-sensorhub-sortable": false
    }
  },
  "additionalProperties": false
}