Skip to content
dropin

Read a feed, enriched

GET
/v1/feeds/{group}/{id}
curl --request GET \
  --url 'http://localhost:3000/v1/feeds/example/example?limit=20' \
  --header 'Authorization: Bearer <token>'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
group
required
string
id
required
string

Query Parameters

Section titled “Query Parameters”
limit
integer
default: 20 >= 1 <= 100
cursor
deprecated
string

Deprecated alias for next. next wins if both are sent.

next
string

Opaque paging token. Pass the next value from the previous page.

Responses

Section titled “Responses”

200

Section titled “200”

A page of activities, reverse-chronological. On an uncursored request the page also carries the promoted sidecar.

Media typeapplication/json
object
results
required
Array
next
required

Opaque cursor. Null when no further page.

string | null
results
required
Array<object>
object
id
required
string format: uuid
actor
required
string
verb
required
string
object
required
string
target
string | null
foreign_id
string | null
time
required
string format: date-time
custom
required
object
key
additional properties
any
origin_feed
required
string
reaction_counts
required
object
key
additional properties
integer
comment_count
required
integer
actor_user

Enriched from users.custom when actor parses as user:. Null otherwise.

object | null
own_reactions

Omitted for server tokens — no caller identity.

Array<string>
refs
required

Objects this activity points at, as type:id. Resolved into the feed read’s objects sidecar. Max 4, no duplicates.

Array<string>
edited_at
required

Null until the activity is first patched.

string | null format: date-time
version
required

Row version. Starts at 1 and increments on ANY change to this activity — a patch, a reaction count moving, a soft delete. Compare it against the copy you hold to decide whether to re-render; edited_at marks patches only, so it cannot report the field that changes most.

integer
warnings

Non-fatal problems with the activity that was just WRITTEN. Present only on the response to POST /v1/feeds/{group}/{id}/activities; a feed read never carries it — the read path stays exactly three statements.

actor_user_unresolved: the write succeeded, but actor names a user:<id> with no users row, so actor_user is null and every card renders with no name and no avatar until that user is upserted. Without this field a correct write and a broken one are byte-identical. A non-user: actor (system:jobs) never enriches by design and is NOT warned about.

Array<string>
Allowed values: actor_user_unresolved
promoted

Promoted activities this caller is eligible for. Present ONLY when the request carried no cursor/next — absent (not empty) on every subsequent page, so one delivery per feed open needs no server-side state. These rows are NOT in results and never affect next: the cursor is a position in the real feed, and a promoted row shifting it would skip or repeat real activities. This is the eligible set, not a slot assignment — cache it client-side and place it as often as you like (see the react SDK’s promotedPosition / promotedRepeatEvery).

Array<object>

A promoted activity as delivered in a feed read’s promoted sidecar. Activity-shaped so the same render path works, but it is NOT an activity: it has no time, no origin_feed, no reactions, and it was never fanned out to anyone’s feed. Targeting fields (audience) and counters (served_count) are deliberately absent here — exposing the audience would leak the tenant’s segmentation to end users.

object
id
required
string format: uuid
actor
required
string
verb
required
string
object
required
string
custom
required
object
key
additional properties
any
promoted
required

Always true. Present so a merged render path can branch on it.

boolean
objects

Refs on this page, resolved. Keyed by type:id. ABSENT (not empty) when no activity on the page carries a ref — the same absent-vs-empty convention as promoted. A ref with no stored object is simply missing from the map, not an error.

object
key
additional properties

Tenant-owned mutable data that activities point at. Opaque to dropin — we store, update, and return custom, and never interpret it. Writes are server-token only.

object
type
required
string
id
required
string
custom
required
object
key
additional properties
any
updated_at
required
string format: date-time
Example
{
  "results": [
    {
      "actor": "user:alice",
      "verb": "post",
      "object": "workout:123",
      "origin_feed": "user:alice",
      "reaction_counts": {
        "like": 3
      },
      "own_reactions": [
        "like"
      ],
      "refs": [
        "session:1234"
      ],
      "warnings": [
        "actor_user_unresolved"
      ]
    }
  ],
  "promoted": [
    {
      "actor": "system:fcurban",
      "verb": "promote",
      "object": "game:8842",
      "promoted": true
    }
  ],
  "objects": {
    "additionalProperty": {
      "type": "session",
      "id": "1234"
    }
  }
}

401

Section titled “401”

Invalid, expired, revoked, or absent token.

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: VALIDATION_FAILED UNAUTHENTICATED FORBIDDEN NOT_FOUND CONFLICT RATE_LIMITED INTERNAL CONTENT_REJECTED
message
required
string
requestId
required
string
fields

Present only for VALIDATION_FAILED.

Array<object>
object
path
string
message
string
Example
{
  "error": {
    "code": "VALIDATION_FAILED"
  }
}

429

Section titled “429”

Rate limit exceeded.

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: VALIDATION_FAILED UNAUTHENTICATED FORBIDDEN NOT_FOUND CONFLICT RATE_LIMITED INTERNAL CONTENT_REJECTED
message
required
string
requestId
required
string
fields

Present only for VALIDATION_FAILED.

Array<object>
object
path
string
message
string
Example
{
  "error": {
    "code": "VALIDATION_FAILED"
  }
}

Headers

Section titled “Headers”
Retry-After
integer