Feeds

What changed since a cursor — the polling primitive

One stream, two checkpoint owners. Stateful callers pass cursor:“latest”, then store each next_cursor themselves; that first call only establishes the checkpoint and returns no events, so poll again with the returned next_cursor. Stateless scheduled agents pass consumer_id; smry retains the acknowledged position and the consumer’s saved where predicate. Pass exactly one. Managed batches repeat until their next_cursor is acknowledged. Every response also carries a capped source-health attention block. To read what is already there rather than what changes next, use query_feeds.

POST

https://api.smry.ai

feeds

changes

What changed since a cursor — the polling primitive

curl --request POST \
  --url https://api.smry.ai/v1/feeds/changes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

import requests

url = "https://api.smry.ai/v1/feeds/changes"

payload = {}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({})
};

fetch('https://api.smry.ai/v1/feeds/changes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "object": "feed_changes",
  "events": [
    {
      "type": "entry.discovered",
      "entry": {}
    }
  ],
  "has_more": true,
  "next_cursor": "<string>",
  "checkpoint": {
    "owner": "caller",
    "consumer_id": 123,
    "ack_required": true
  },
  "attention": {
    "stalled": [
      {}
    ],
    "stalled_count": 123,
    "erroring": [
      {}
    ],
    "erroring_count": 123,
    "never_produced": [
      {}
    ],
    "never_produced_count": 123
  }
}

{
  "error": "cursor: expected a next_cursor from a previous response.",
  "code": "invalid_request",
  "field": "where.published_after",
  "hint": "<string>",
  "retryable": true,
  "retryAfter": 123,
  "details": "<string>"
}

{
  "error": "cursor: expected a next_cursor from a previous response.",
  "code": "invalid_request",
  "field": "where.published_after",
  "hint": "<string>",
  "retryable": true,
  "retryAfter": 123,
  "details": "<string>"
}

{
  "error": "cursor: expected a next_cursor from a previous response.",
  "code": "invalid_request",
  "field": "where.published_after",
  "hint": "<string>",
  "retryable": true,
  "retryAfter": 123,
  "details": "<string>"
}

{
  "error": "cursor: expected a next_cursor from a previous response.",
  "code": "invalid_request",
  "field": "where.published_after",
  "hint": "<string>",
  "retryable": true,
  "retryAfter": 123,
  "details": "<string>"
}

{
  "error": "cursor: expected a next_cursor from a previous response.",
  "code": "invalid_request",
  "field": "where.published_after",
  "hint": "<string>",
  "retryable": true,
  "retryAfter": 123,
  "details": "<string>"
}

Authorizations

Authorization

string

header

required

Clerk OAuth 2.0 Authorization Code flow with PKCE. Request the minimum scope required by the operation.

Body

application/json

cursor

string

Caller-managed progress: "latest" to start, then the next_cursor you stored.

Required string length: 1 - 500

consumer_id

integer

smry-managed progress: poll this consumer's saved predicate. Omit cursor and where.

Required range: x >= 1

limit

integer

Required range: 1 <= x <= 500

where

object

Entry selection predicate: fields AND together; omit a field to not filter on it. Source queries/mutations accept only collection and source; use query having for source-health filters.

Hide child attributes

where.discovered_after

string

When smry first saw the entry. Backfill makes old posts look new here, so use it for diffs, not for "what's new". Relative window ("7d", "36h", "45m", "2w"), "now", or ISO date.

Required string length: 1 - 64

where.discovered_before

string

Relative window ("7d", "36h", "45m", "2w"), "now", or ISO date.

Required string length: 1 - 64

where.published_after

string

When the source published the entry (entries with no publish date are excluded; use top-level since to include them). Relative window ("7d", "36h", "45m", "2w"), "now", or ISO date.

Required string length: 1 - 64

where.published_before

string

Relative window ("7d", "36h", "45m", "2w"), "now", or ISO date.

Required string length: 1 - 64

where.collection

(integer | string)[]

Required array length: 1 - 20 elements

A collection id or its exact name.

Required range: x >= 1

where.source

object

Hide child attributes

where.source.include

(integer | string)[]

Required array length: 1 - 100 elements

A source id (from any v2 response) or its title. Reads also accept a fragment that matches exactly one title.

Required range: x >= 1

where.source.exclude

(integer | string)[]

Required array length: 1 - 100 elements

A source id (from any v2 response) or its title. Reads also accept a fragment that matches exactly one title.

Required range: x >= 1

where.unread

boolean

true = only unread entries, false = only read entries.

where.classification

object

The Collection filter's binary delivery decision and optional underlying assessment. Requires exactly one Collection.

Hide child attributes

where.classification.decision

required

Allowed value: "include"

where.classification.assessment

Allowed value: "relevant"

where.match

string

Case-insensitive text match over title and summary. "a OR b" matches either.

Required string length: 1 - 500

fields

string[]

Project event entries to these fields; ["id"] is the cheapest diff. id is always included.

Allowed value: "id"

attention_limit

integer

Sources listed per attention bucket (default 5; the *_count fields always carry the full tally). Pass up to 500 for the exhaustive roster, 0 for counts only.

Required range: 0 <= x <= 500

Response

What changed since a cursor — the polling primitive. The operation succeeded.

object

string

required

Allowed value: "feed_changes"

events

object[]

required

Hide child attributes

events.type

enum<string>

required

Available options:

entry.discovered,

entry.classified

events.entry

object

required

The entry, projected to the requested fields. id is always present. entry.classified events also carry the filter's decision, assessment, reason, and filter_revision.

has_more

boolean

required

next_cursor

string

required

checkpoint

object

required

Hide child attributes

checkpoint.owner

enum<string>

required

Available options:

caller,

smry

checkpoint.consumer_id

integer | null

required

checkpoint.ack_required

boolean

required

True only for managed delivery; acknowledge next_cursor after processing every event, including an empty batch.

attention

object

required

Source health, capped to five per bucket (stalled: longest silent first; erroring and never_produced: alphabetical); the *_count fields carry the full tally. Query select:"sources" with having for the complete list.

Hide child attributes

attention.stalled

object[]

required

attention.stalled_count

integer

required

attention.erroring

object[]

required

attention.erroring_count

integer

required

attention.never_produced

object[]

required

attention.never_produced_count

integer

required

Last modified on September 13, 2026

What changed since a cursor — the polling primitive

curl --request POST \
  --url https://api.smry.ai/v1/feeds/changes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

import requests

url = "https://api.smry.ai/v1/feeds/changes"

payload = {}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({})
};

fetch('https://api.smry.ai/v1/feeds/changes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "object": "feed_changes",
  "events": [
    {
      "type": "entry.discovered",
      "entry": {}
    }
  ],
  "has_more": true,
  "next_cursor": "<string>",
  "checkpoint": {
    "owner": "caller",
    "consumer_id": 123,
    "ack_required": true
  },
  "attention": {
    "stalled": [
      {}
    ],
    "stalled_count": 123,
    "erroring": [
      {}
    ],
    "erroring_count": 123,
    "never_produced": [
      {}
    ],
    "never_produced_count": 123
  }
}

{
  "error": "cursor: expected a next_cursor from a previous response.",
  "code": "invalid_request",
  "field": "where.published_after",
  "hint": "<string>",
  "retryable": true,
  "retryAfter": 123,
  "details": "<string>"
}

{
  "error": "cursor: expected a next_cursor from a previous response.",
  "code": "invalid_request",
  "field": "where.published_after",
  "hint": "<string>",
  "retryable": true,
  "retryAfter": 123,
  "details": "<string>"
}

{
  "error": "cursor: expected a next_cursor from a previous response.",
  "code": "invalid_request",
  "field": "where.published_after",
  "hint": "<string>",
  "retryable": true,
  "retryAfter": 123,
  "details": "<string>"
}

{
  "error": "cursor: expected a next_cursor from a previous response.",
  "code": "invalid_request",
  "field": "where.published_after",
  "hint": "<string>",
  "retryable": true,
  "retryAfter": 123,
  "details": "<string>"
}

{
  "error": "cursor: expected a next_cursor from a previous response.",
  "code": "invalid_request",
  "field": "where.published_after",
  "hint": "<string>",
  "retryable": true,
  "retryAfter": 123,
  "details": "<string>"
}

Overview

Account

Articles

Library

Feeds

Collections

Consumers

Monitors

What changed since a cursor — the polling primitive

Authorizations

Body

Response