REST API / Collections

`perception_statements`

CollectionRequires PerceptionLarge: filter on indexed fields

Atomic statements extracted from mentions and AI answers. Raw statements do not imply inclusion in Perception headline counts. Source quotes and summaries are masked outside the app.

Max rows per query: 100
Default order: id asc
Required filter: one of project_id, id, item_id, mention_id, prompt_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.	✓	–
`source_kind` indexed	`string`	Source kind. `MENTION` `AI_ANSWER` `PROBE_ANSWER`	✓	–
`mention_id` nullable indexed	`string`	Related mention ID.	✓	✓
`prompt_id` nullable indexed	`string`	Related prompt ID.	✓	✓
`engine` nullable	`string`	Answer engine. `CHATGPT` `GOOGLE_AIO`	–	–
`subject_label` nullable indexed	`string`	Tracked subject label.	✓	✓
`type` indexed	`string`	Statement type. `CLAIM` `QUESTION` `OBJECTION` `PROBLEM` `NONE`	✓	–
`role`	`string`	Source role. `FIRST_HAND` `BYSTANDER` `VENDOR_PROMO` `LIST_LINE` `PAGE` `AI`	–	–
`voice`	`string`	Source voice. `PERSON` `PAGE` `AI` `NONE`	–	–
`gist` nullable redacted	`string`	Short summary, masked for LinkedIn or deleted sources.	–	–
`quote` nullable redacted	`string`	Verbatim quote, masked for LinkedIn or deleted sources.	–	–
`stance` nullable	`string`	Sentiment stance. `POSITIVE` `NEUTRAL` `NEGATIVE`	–	–
`polarity` nullable	`string`	Claim polarity. `ASSERTS` `DENIES`	–	–
`theme_key` nullable	`string`	Project theme key.	–	–
`item_id` nullable indexed	`string`	Grouped Perception item ID.	✓	✓
`clock_at` nullable indexed	`datetime`	Statement window clock. Filter with a source kind to use the project/source/time index.	✓	✓
`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, source_kind, mention_id, prompt_id
FROM perception_statements
WHERE project_id = $1
ORDER BY id ASC
LIMIT 25

Calling it

MCP

Tool call

query({"sql":"SELECT id, project_id, source_kind, mention_id, prompt_id FROM perception_statements WHERE project_id = $1 ORDER BY id ASC 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, source_kind, mention_id, prompt_id FROM perception_statements WHERE project_id = $1 ORDER BY id ASC LIMIT 25",
  "params": [
    "<value 1>"
  ]
}
JSON

Row JSON Schema

json

{
  "type": "object",
  "description": "Atomic statements extracted from mentions and AI answers. Raw statements do not imply inclusion in Perception headline counts. Source quotes and summaries are masked outside the app.",
  "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
    },
    "source_kind": {
      "type": "string",
      "description": "Source kind.",
      "enum": [
        "MENTION",
        "AI_ANSWER",
        "PROBE_ANSWER"
      ],
      "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": false
    },
    "mention_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Related mention ID.",
      "x-sensorhub-indexed": true,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": true,
      "x-sensorhub-sortable": true
    },
    "prompt_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Related prompt ID.",
      "x-sensorhub-indexed": true,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": true,
      "x-sensorhub-sortable": true
    },
    "engine": {
      "type": [
        "string",
        "null"
      ],
      "description": "Answer engine.",
      "enum": [
        "CHATGPT",
        "GOOGLE_AIO",
        null
      ],
      "x-sensorhub-filter-operators": [],
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": false,
      "x-sensorhub-sortable": false
    },
    "subject_label": {
      "type": [
        "string",
        "null"
      ],
      "description": "Tracked subject label.",
      "x-sensorhub-indexed": true,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": true,
      "x-sensorhub-sortable": true
    },
    "type": {
      "type": "string",
      "description": "Statement type.",
      "enum": [
        "CLAIM",
        "QUESTION",
        "OBJECTION",
        "PROBLEM",
        "NONE"
      ],
      "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": false
    },
    "role": {
      "type": "string",
      "description": "Source role.",
      "enum": [
        "FIRST_HAND",
        "BYSTANDER",
        "VENDOR_PROMO",
        "LIST_LINE",
        "PAGE",
        "AI"
      ],
      "x-sensorhub-filter-operators": [],
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": false,
      "x-sensorhub-sortable": false
    },
    "voice": {
      "type": "string",
      "description": "Source voice.",
      "enum": [
        "PERSON",
        "PAGE",
        "AI",
        "NONE"
      ],
      "x-sensorhub-filter-operators": [],
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": false,
      "x-sensorhub-sortable": false
    },
    "gist": {
      "type": [
        "string",
        "null"
      ],
      "description": "Short summary, 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
    },
    "quote": {
      "type": [
        "string",
        "null"
      ],
      "description": "Verbatim quote, 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
    },
    "stance": {
      "type": [
        "string",
        "null"
      ],
      "description": "Sentiment stance.",
      "enum": [
        "POSITIVE",
        "NEUTRAL",
        "NEGATIVE",
        null
      ],
      "x-sensorhub-filter-operators": [],
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": false,
      "x-sensorhub-sortable": false
    },
    "polarity": {
      "type": [
        "string",
        "null"
      ],
      "description": "Claim polarity.",
      "enum": [
        "ASSERTS",
        "DENIES",
        null
      ],
      "x-sensorhub-filter-operators": [],
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": false,
      "x-sensorhub-sortable": false
    },
    "theme_key": {
      "type": [
        "string",
        "null"
      ],
      "description": "Project theme key.",
      "x-sensorhub-indexed": false,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": false,
      "x-sensorhub-sortable": false
    },
    "item_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Grouped Perception item ID.",
      "x-sensorhub-indexed": true,
      "x-sensorhub-searchable": false,
      "x-sensorhub-aggregatable": true,
      "x-sensorhub-filterable": true,
      "x-sensorhub-sortable": true
    },
    "clock_at": {
      "type": [
        "string",
        "null"
      ],
      "description": "Statement window clock. Filter with a source kind to use the project/source/time index.",
      "format": "date-time",
      "x-sensorhub-indexed": true,
      "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
}