REST API / Collections

`perception_threads`

CollectionRequires Perception

Qualifying threads only: CRITICAL requires at least 10 counted people and at least 70% negative opinions; COMPLAINT is competitor-only. OWN has no COMPLAINT rows. Empty results do not establish that there are no discussions. Check processing status and ordinary discussions with read perception_part, part=overview, include_threads=negative. Text is masked for LinkedIn, deleted or missing representative sources; personal URLs and communities are masked.

Max rows per query: 100
Default order: id asc
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.	✓	–
`subject_kind`	`string`	Tracked subject kind. `OWN` `COMPETITOR` `TOPIC`	✓	✓
`subject_label`	`string`	Tracked subject label.	✓	✓
`kind`	`string`	Thread kind. `CRITICAL` `COMPLAINT`	✓	–
`window_days`	`integer`	Snapshot window in days.	✓	✓
`url` nullable redacted	`string`	Public thread URL.	–	–
`title` nullable redacted	`string`	Public thread title.	–	–
`channel`	`string`	Source channel. `CHATGPT` `GOOGLE_AIO` `WEB_SERP` `REDDIT` `XCOM` `LINKEDIN` `FACEBOOK` `QUORA` `STACKOVERFLOW` `GITHUB` `INSTAGRAM` `YOUTUBE` `TIKTOK` `FORUM`	✓	✓
`lens`	`string`	Lens tab.	✓	✓
`community` nullable redacted	`string`	Public source community.	–	–
`started_at` nullable	`datetime`	Thread start time.	✓	✓
`last_opinion_at` nullable	`datetime`	Latest opinion time.	✓	✓
`people`	`integer`	Distinct people.	✓	✓
`opinions`	`integer`	Counted opinions.	✓	✓
`positive`	`integer`	Positive count.	✓	✓
`neutral`	`integer`	Neutral count.	✓	✓
`negative`	`integer`	Negative count.	✓	✓
`theme_key` nullable	`string`	Majority theme key.	✓	✓
`cited_in_ai`	`boolean`	Whether cited by AI.	✓	✓
`engagement_score` nullable	`integer`	Engagement score.	✓	✓
`mention_id`	`string`	Representative mention ID.	✓	✓
`computed_at`	`datetime`	Snapshot computation time.	✓	✓
`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, subject_kind, subject_label, kind
FROM perception_threads
ORDER BY id ASC
LIMIT 25

Calling it

MCP

Tool call

query({"sql":"SELECT id, project_id, subject_kind, subject_label, kind FROM perception_threads ORDER BY id ASC LIMIT 25"})

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, subject_kind, subject_label, kind FROM perception_threads ORDER BY id ASC LIMIT 25"
}
JSON

Row JSON Schema

json

{
  "type": "object",
  "description": "Qualifying threads only: CRITICAL requires at least 10 counted people and at least 70% negative opinions; COMPLAINT is competitor-only. OWN has no COMPLAINT rows. Empty results do not establish that there are no discussions. Check processing status and ordinary discussions with read perception_part, part=overview, include_threads=negative. Text is masked for LinkedIn, deleted or missing representative sources; personal URLs and communities are masked.",
  "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
    },
    "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": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": true,
      "x-sensorhub-sortable": true
    },
    "subject_label": {
      "type": "string",
      "description": "Tracked subject label.",
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": true,
      "x-sensorhub-sortable": true
    },
    "kind": {
      "type": "string",
      "description": "Thread kind.",
      "enum": [
        "CRITICAL",
        "COMPLAINT"
      ],
      "x-sensorhub-filter-operators": [
        "=",
        "!=",
        "<>",
        "IN",
        "NOT IN",
        "IS NULL",
        "IS NOT NULL"
      ],
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": true,
      "x-sensorhub-sortable": false
    },
    "window_days": {
      "type": "integer",
      "description": "Snapshot window in days.",
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": true,
      "x-sensorhub-sortable": true
    },
    "url": {
      "type": [
        "string",
        "null"
      ],
      "description": "Public thread URL.",
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": false,
      "x-sensorhub-filterable": false,
      "x-sensorhub-sortable": false
    },
    "title": {
      "type": [
        "string",
        "null"
      ],
      "description": "Public thread title.",
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": false,
      "x-sensorhub-filterable": false,
      "x-sensorhub-sortable": false
    },
    "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": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": true,
      "x-sensorhub-sortable": true
    },
    "lens": {
      "type": "string",
      "description": "Lens tab.",
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": true,
      "x-sensorhub-sortable": true
    },
    "community": {
      "type": [
        "string",
        "null"
      ],
      "description": "Public source community.",
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": false,
      "x-sensorhub-filterable": false,
      "x-sensorhub-sortable": false
    },
    "started_at": {
      "type": [
        "string",
        "null"
      ],
      "description": "Thread start time.",
      "format": "date-time",
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": true,
      "x-sensorhub-sortable": true
    },
    "last_opinion_at": {
      "type": [
        "string",
        "null"
      ],
      "description": "Latest opinion time.",
      "format": "date-time",
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": true,
      "x-sensorhub-sortable": true
    },
    "people": {
      "type": "integer",
      "description": "Distinct people.",
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": true,
      "x-sensorhub-sortable": true
    },
    "opinions": {
      "type": "integer",
      "description": "Counted opinions.",
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": true,
      "x-sensorhub-sortable": true
    },
    "positive": {
      "type": "integer",
      "description": "Positive count.",
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": true,
      "x-sensorhub-sortable": true
    },
    "neutral": {
      "type": "integer",
      "description": "Neutral count.",
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": true,
      "x-sensorhub-sortable": true
    },
    "negative": {
      "type": "integer",
      "description": "Negative count.",
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": true,
      "x-sensorhub-sortable": true
    },
    "theme_key": {
      "type": [
        "string",
        "null"
      ],
      "description": "Majority theme key.",
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": true,
      "x-sensorhub-sortable": true
    },
    "cited_in_ai": {
      "type": "boolean",
      "description": "Whether cited by AI.",
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": true,
      "x-sensorhub-sortable": true
    },
    "engagement_score": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Engagement score.",
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": true,
      "x-sensorhub-sortable": true
    },
    "mention_id": {
      "type": "string",
      "description": "Representative mention ID.",
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": true,
      "x-sensorhub-sortable": true
    },
    "computed_at": {
      "type": "string",
      "description": "Snapshot computation time.",
      "format": "date-time",
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": true,
      "x-sensorhub-sortable": true
    },
    "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
}