getFeed

GET

/feed

const url = 'http://localhost:8080/api/v1/feed?circleId=per_01j9x3k8m2q4r5s6t7v8w9y0z1&shuffle=0&limit=20';
const options = {method: 'GET', headers: {cookie: 'hs_session=<hs_session>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'http://localhost:8080/api/v1/feed?circleId=per_01j9x3k8m2q4r5s6t7v8w9y0z1&shuffle=0&limit=20' \
  --cookie hs_session=<hs_session>

Ranked feed with hearth picks. Algorithm in docs/06-feed.md.

Authorizations

cookieAuth
bearerAuth

Parameters

Query Parameters

circleId

string

/^[a-z]{2,3}_[0-9a-hjkmnp-tv-z]{26}$/

Omit for “All” (circles the member has in feed).

shuffle

integer

Increment to re-roll hearth picks. Ignored when cursor is set.

limit

integer

default: 20 >= 5 <= 50

cursor

string

<= 512 characters

Responses

200

Feed page.

application/json

object

entries

required

Array

One of: discriminator: type

object

type

required

string

Allowed value: moment

moment

required

object

required

string

/^[a-z]{2,3}_[0-9a-hjkmnp-tv-z]{26}$/

person

required

object

required

string

/^[a-z]{2,3}_[0-9a-hjkmnp-tv-z]{26}$/

displayName

required

string

relationLabel

string | null

kind

required

string

Allowed values: family friend creator other

closeness

required

1 = closest. Weights the feed and hearth picks.

integer

>= 1 <= 3

avatar

One of:

object
null

object

required

string

/^[a-z]{2,3}_[0-9a-hjkmnp-tv-z]{26}$/

url

required

Signed URL, valid 24 h.

string

thumbUrl

string

cardUrl

string

posterUrl

string

mime

required

string

width

integer

height

integer

durationMs

integer

blurhash

string

alt

string

account

required

object

required

string

/^[a-z]{2,3}_[0-9a-hjkmnp-tv-z]{26}$/

platform

required

string

Allowed values: instagram facebook line wechat bluesky x douyin xiaohongshu truthsocial

handle

required

string

displayName

string | null

profileUrl

required

string format: uri

deepLinks

required

Client picks app link on mobile when installed, else web.

object

web

required

string format: uri

ios

string

android

string

copyValue

Value to copy when no link exists (e.g. WeChat ID).

string

hintKey

I18n key with instructions, e.g. “platformWechatOpenHint”.

string

kind

required

string

Allowed values: story post video link text

text

string | null

lang

string | null

url

required

string format: uri

publishedAt

required

string format: date-time

expiresAt

One of:

string
null

string format: date-time

media

required

Array<object>

object

required

string

/^[a-z]{2,3}_[0-9a-hjkmnp-tv-z]{26}$/

url

required

Signed URL, valid 24 h.

string

thumbUrl

string

cardUrl

string

posterUrl

string

mime

required

string

width

integer

height

integer

durationMs

integer

blurhash

string

alt

string

seen

required

boolean

source

required

string

Allowed values: server agent extension

capturedBy

One of:

object
null

object

required

string

/^[a-z]{2,3}_[0-9a-hjkmnp-tv-z]{26}$/

displayName

required

string

avatar

One of:

object
null

object

required

string

/^[a-z]{2,3}_[0-9a-hjkmnp-tv-z]{26}$/

url

required

Signed URL, valid 24 h.

string

thumbUrl

string

cardUrl

string

posterUrl

string

mime

required

string

width

integer

height

integer

durationMs

integer

blurhash

string

alt

string

summary

AI-written summary in summaryLocale; null when none or hidden by the viewer’s setting.

string | null

summaryLocale

One of:

string
null

string

Allowed values: en zh-Hans th

nextCursor

required

string | null

seed

required

string

generatedAt

required

string format: date-time

Examples

seed

Derived from fixtures/seed.json.

{
  "entries": [
    {
      "type": "recent_visits",
      "visits": [
        {
          "account": {
            "deepLinks": {
              "android": "https://www.instagram.com/_u/mom.wong.bkk/",
              "ios": "instagram://user?username=mom.wong.bkk",
              "web": "https://www.instagram.com/mom.wong.bkk/"
            },
            "displayName": null,
            "handle": "mom.wong.bkk",
            "id": "acc_01j93283xpmc4y04hy7rmmt7y7",
            "platform": "instagram",
            "profileUrl": "https://www.instagram.com/mom.wong.bkk/"
          },
          "byMe": true,
          "counts": {
            "post": 0,
            "story": 3,
            "video": 0
          },
          "momentIds": [
            "mom_01j9adj9t141gzfk8s7x1yyg4j",
            "mom_01j991j97j1nk24fm0mgptj50b",
            "mom_01j9nrjezabk0hz8xwak44q3yj"
          ],
          "person": {
            "avatar": null,
            "closeness": 1,
            "displayName": "Mom",
            "id": "per_01j9wst6a8vjc69r66y6fj70t5",
            "kind": "family",
            "relationLabel": "แม่"
          },
          "visitedAt": "2026-10-17T08:40:00.000Z",
          "visitedBy": null
        }
      ]
    },
    {
      "moment": {
        "account": {
          "deepLinks": {
            "android": "https://www.instagram.com/_u/mom.wong.bkk/",
            "ios": "instagram://user?username=mom.wong.bkk",
            "web": "https://www.instagram.com/mom.wong.bkk/"
          },
          "displayName": null,
          "handle": "mom.wong.bkk",
          "id": "acc_01j93283xpmc4y04hy7rmmt7y7",
          "platform": "instagram",
          "profileUrl": "https://www.instagram.com/mom.wong.bkk/"
        },
        "capturedBy": {
          "avatar": null,
          "displayName": "Mali",
          "id": "mem_01j9kt0d8rwgmhnmxkmv0frnr0"
        },
        "expiresAt": "2026-10-18T07:30:00.000Z",
        "id": "mom_01j9nrjezabk0hz8xwak44q3yj",
        "kind": "story",
        "lang": null,
        "media": [
          {
            "alt": "White orchids in a clay pot",
            "cardUrl": "/fixtures/media/orchid.jpg",
            "height": 240,
            "id": "med_01j9a1b2c3d4e5f6g7h8j9k003",
            "mime": "image/jpeg",
            "thumbUrl": "/fixtures/media/orchid.jpg",
            "url": "/fixtures/media/orchid.jpg",
            "width": 320
          }
        ],
        "person": {
          "avatar": null,
          "closeness": 1,
          "displayName": "Mom",
          "id": "per_01j9wst6a8vjc69r66y6fj70t5",
          "kind": "family",
          "relationLabel": "แม่"
        },
        "publishedAt": "2026-10-17T07:30:00.000Z",
        "seen": false,
        "source": "extension",
        "summary": null,
        "summaryLocale": null,
        "text": null,
        "url": "https://www.instagram.com/stories/mom.wong.bkk/3456789012345678903/"
      },
      "type": "moment"
    },
    {
      "moment": {
        "account": {
          "deepLinks": {
            "android": "https://www.instagram.com/_u/mom.wong.bkk/",
            "ios": "instagram://user?username=mom.wong.bkk",
            "web": "https://www.instagram.com/mom.wong.bkk/"
          },
          "displayName": null,
          "handle": "mom.wong.bkk",
          "id": "acc_01j93283xpmc4y04hy7rmmt7y7",
          "platform": "instagram",
          "profileUrl": "https://www.instagram.com/mom.wong.bkk/"
        },
        "capturedBy": {
          "avatar": null,
          "displayName": "Mali",
          "id": "mem_01j9kt0d8rwgmhnmxkmv0frnr0"
        },
        "expiresAt": "2026-10-18T07:12:00.000Z",
        "id": "mom_01j991j97j1nk24fm0mgptj50b",
        "kind": "story",
        "lang": null,
        "media": [
          {
            "alt": "Market aisle with flower garlands",
            "cardUrl": "/fixtures/media/market-2.jpg",
            "height": 240,
            "id": "med_01j9a1b2c3d4e5f6g7h8j9k002",
            "mime": "image/jpeg",
            "thumbUrl": "/fixtures/media/market-2.jpg",
            "url": "/fixtures/media/market-2.jpg",
            "width": 320
          }
        ],
        "person": {
          "avatar": null,
          "closeness": 1,
          "displayName": "Mom",
          "id": "per_01j9wst6a8vjc69r66y6fj70t5",
          "kind": "family",
          "relationLabel": "แม่"
        },
        "publishedAt": "2026-10-17T07:12:00.000Z",
        "seen": false,
        "source": "extension",
        "summary": null,
        "summaryLocale": null,
        "text": null,
        "url": "https://www.instagram.com/stories/mom.wong.bkk/3456789012345678902/"
      },
      "type": "moment"
    },
    {
      "moment": {
        "account": {
          "deepLinks": {
            "android": "https://www.instagram.com/_u/mom.wong.bkk/",
            "ios": "instagram://user?username=mom.wong.bkk",
            "web": "https://www.instagram.com/mom.wong.bkk/"
          },
          "displayName": null,
          "handle": "mom.wong.bkk",
          "id": "acc_01j93283xpmc4y04hy7rmmt7y7",
          "platform": "instagram",
          "profileUrl": "https://www.instagram.com/mom.wong.bkk/"
        },
        "capturedBy": {
          "avatar": null,
          "displayName": "Mali",
          "id": "mem_01j9kt0d8rwgmhnmxkmv0frnr0"
        },
        "expiresAt": "2026-10-18T07:00:00.000Z",
        "id": "mom_01j9adj9t141gzfk8s7x1yyg4j",
        "kind": "story",
        "lang": null,
        "media": [
          {
            "alt": "Market stall with oranges and bananas",
            "cardUrl": "/fixtures/media/market-1.jpg",
            "height": 240,
            "id": "med_01j9a1b2c3d4e5f6g7h8j9k001",
            "mime": "image/jpeg",
            "thumbUrl": "/fixtures/media/market-1.jpg",
            "url": "/fixtures/media/market-1.jpg",
            "width": 320
          }
        ],
        "person": {
          "avatar": null,
          "closeness": 1,
          "displayName": "Mom",
          "id": "per_01j9wst6a8vjc69r66y6fj70t5",
          "kind": "family",
          "relationLabel": "แม่"
        },
        "publishedAt": "2026-10-17T07:00:00.000Z",
        "seen": false,
        "source": "extension",
        "summary": "แม่แชร์ภาพตลาดนัดวันอาทิตย์: ส้ม กล้วยไม้ และแผงทุเรียน",
        "summaryLocale": "th",
        "text": null,
        "url": "https://www.instagram.com/stories/mom.wong.bkk/3456789012345678901/"
      },
      "type": "moment"
    },
    {
      "pick": {
        "account": {
          "deepLinks": {
            "android": "https://line.me/R/ti/p/~grandma_noi",
            "ios": "https://line.me/R/ti/p/~grandma_noi",
            "web": "https://line.me/R/ti/p/~grandma_noi"
          },
          "displayName": null,
          "handle": "~grandma_noi",
          "id": "acc_01j9e81cm1p0x7vysze8aeqsje",
          "platform": "line",
          "profileUrl": "https://line.me/R/ti/p/~grandma_noi"
        },
        "copyVariant": 2,
        "daysSinceVisit": 2,
        "id": "pick_per_01j9w5jqj9nm7gdsybfz53mcjr_20261017",
        "person": {
          "avatar": null,
          "closeness": 1,
          "displayName": "Grandma Noi",
          "id": "per_01j9w5jqj9nm7gdsybfz53mcjr",
          "kind": "family",
          "relationLabel": "ยาย"
        },
        "reason": "closed_platform"
      },
      "type": "hearth_pick"
    },
    {
      "pick": {
        "account": {
          "deepLinks": {
            "android": "https://x.com/somsak_runs",
            "ios": "https://x.com/somsak_runs",
            "web": "https://x.com/somsak_runs"
          },
          "displayName": null,
          "handle": "somsak_runs",
          "id": "acc_01j9dfpvstm7aq628gwwc9xkq3",
          "platform": "x",
          "profileUrl": "https://x.com/somsak_runs"
        },
        "copyVariant": 5,
        "daysSinceVisit": 14,
        "id": "pick_per_01j9rwtm99tsb5zjfh16k89915_20261017",
        "person": {
          "avatar": null,
          "closeness": 2,
          "displayName": "Somsak",
          "id": "per_01j9rwtm99tsb5zjfh16k89915",
          "kind": "friend",
          "relationLabel": null
        },
        "reason": "quiet"
      },
      "type": "hearth_pick"
    },
    {
      "moment": {
        "account": {
          "deepLinks": {
            "android": "https://www.instagram.com/_u/lin.cooks/",
            "ios": "instagram://user?username=lin.cooks",
            "web": "https://www.instagram.com/lin.cooks/"
          },
          "displayName": null,
          "handle": "lin.cooks",
          "id": "acc_01j9te0skfktnnmw6zvew46azb",
          "platform": "instagram",
          "profileUrl": "https://www.instagram.com/lin.cooks/"
        },
        "capturedBy": null,
        "expiresAt": null,
        "id": "mom_01j9nj3ypeq6k27kf3fad65g2e",
        "kind": "post",
        "lang": null,
        "media": [
          {
            "alt": "Bowl of tom kha with lime and galangal",
            "cardUrl": "/fixtures/media/tom-kha.jpg",
            "height": 240,
            "id": "med_01j9a1b2c3d4e5f6g7h8j9k005",
            "mime": "image/jpeg",
            "thumbUrl": "/fixtures/media/tom-kha.jpg",
            "url": "/fixtures/media/tom-kha.jpg",
            "width": 320
          }
        ],
        "person": {
          "avatar": null,
          "closeness": 2,
          "displayName": "Lin",
          "id": "per_01j9f8r1agkh6g3jp30xcwnytc",
          "kind": "family",
          "relationLabel": "Cousin"
        },
        "publishedAt": "2026-10-17T06:00:00.000Z",
        "seen": false,
        "source": "agent",
        "summary": null,
        "summaryLocale": null,
        "text": "Tom kha, round three. Getting closer to Grandma's.",
        "url": "https://www.instagram.com/p/C9xYzAbCdEf/"
      },
      "type": "moment"
    },
    {
      "moment": {
        "account": {
          "deepLinks": {
            "android": "https://bsky.app/profile/alice.bsky.social",
            "ios": "https://bsky.app/profile/alice.bsky.social",
            "web": "https://bsky.app/profile/alice.bsky.social"
          },
          "displayName": null,
          "handle": "alice.bsky.social",
          "id": "acc_01j9cw1k85px7z7ysr9gtg04cc",
          "platform": "bluesky",
          "profileUrl": "https://bsky.app/profile/alice.bsky.social"
        },
        "capturedBy": null,
        "expiresAt": null,
        "id": "mom_01j9spb675tckf1xpp52928a0q",
        "kind": "post",
        "lang": null,
        "media": [
          {
            "alt": "Frost on vegetable leaves at sunrise",
            "cardUrl": "/fixtures/media/frost.jpg",
            "height": 240,
            "id": "med_01j9a1b2c3d4e5f6g7h8j9k00a",
            "mime": "image/jpeg",
            "thumbUrl": "/fixtures/media/frost.jpg",
            "url": "/fixtures/media/frost.jpg",
            "width": 320
          }
        ],
        "person": {
          "avatar": null,
          "closeness": 2,
          "displayName": "Alice",
          "id": "per_01j9br69ze0ftz3jf7396q38vf",
          "kind": "friend",
          "relationLabel": null
        },
        "publishedAt": "2026-10-17T05:00:00.000Z",
        "seen": false,
        "source": "server",
        "summary": null,
        "summaryLocale": null,
        "text": "First frost on the allotment this morning.",
        "url": "https://bsky.app/profile/alice.bsky.social/post/3l6abcxyz2k2a"
      },
      "type": "moment"
    },
    {
      "moment": {
        "account": {
          "deepLinks": {
            "android": "xhsdiscover://user/5f1a2b3c4d5e6f7a8b9c0d1e",
            "ios": "xhsdiscover://user/5f1a2b3c4d5e6f7a8b9c0d1e",
            "web": "https://www.xiaohongshu.com/user/profile/5f1a2b3c4d5e6f7a8b9c0d1e"
          },
          "displayName": null,
          "handle": "5f1a2b3c4d5e6f7a8b9c0d1e",
          "id": "acc_01j91es8krfwqg9fhg08x4698y",
          "platform": "xiaohongshu",
          "profileUrl": "https://www.xiaohongshu.com/user/profile/5f1a2b3c4d5e6f7a8b9c0d1e"
        },
        "capturedBy": null,
        "expiresAt": null,
        "id": "mom_01j91c6xjprte88d8v9njq55w6",
        "kind": "post",
        "lang": "zh-Hans",
        "media": [
          {
            "alt": "Braised pork belly in a clay pot",
            "cardUrl": "/fixtures/media/hongshaorou-1.jpg",
            "height": 240,
            "id": "med_01j9a1b2c3d4e5f6g7h8j9k007",
            "mime": "image/jpeg",
            "thumbUrl": "/fixtures/media/hongshaorou-1.jpg",
            "url": "/fixtures/media/hongshaorou-1.jpg",
            "width": 320
          },
          {
            "alt": "Close-up of glazed pork belly",
            "cardUrl": "/fixtures/media/hongshaorou-2.jpg",
            "height": 240,
            "id": "med_01j9a1b2c3d4e5f6g7h8j9k008",
            "mime": "image/jpeg",
            "thumbUrl": "/fixtures/media/hongshaorou-2.jpg",
            "url": "/fixtures/media/hongshaorou-2.jpg",
            "width": 320
          },
          {
            "alt": "Braised pork with greens on a plate",
            "cardUrl": "/fixtures/media/hongshaorou-3.jpg",
            "height": 240,
            "id": "med_01j9a1b2c3d4e5f6g7h8j9k009",
            "mime": "image/jpeg",
            "thumbUrl": "/fixtures/media/hongshaorou-3.jpg",
            "url": "/fixtures/media/hongshaorou-3.jpg",
            "width": 320
          }
        ],
        "person": {
          "avatar": null,
          "closeness": 3,
          "displayName": "小厨娘",
          "id": "per_01j9nt02btj9vmesaexmby3q67",
          "kind": "creator",
          "relationLabel": null
        },
        "publishedAt": "2026-10-17T03:00:00.000Z",
        "seen": false,
        "source": "agent",
        "summary": null,
        "summaryLocale": null,
        "text": "三步做出不粘锅的红烧肉，收藏起来周末试试！",
        "url": "https://www.xiaohongshu.com/explore/64f1a2b3c4d5e6f7a8b9c0d1"
      },
      "type": "moment"
    },
    {
      "section": "earlier",
      "type": "section"
    },
    {
      "moment": {
        "account": {
          "deepLinks": {
            "android": "https://truthsocial.com/@realexample",
            "ios": "https://truthsocial.com/@realexample",
            "web": "https://truthsocial.com/@realexample"
          },
          "displayName": null,
          "handle": "realexample",
          "id": "acc_01j93fce9xpx1fxafb7vaej1he",
          "platform": "truthsocial",
          "profileUrl": "https://truthsocial.com/@realexample"
        },
        "capturedBy": null,
        "expiresAt": null,
        "id": "mom_01j9kfpftghhdd4p0nk6w1s7ca",
        "kind": "link",
        "lang": null,
        "media": [],
        "person": {
          "avatar": null,
          "closeness": 3,
          "displayName": "Example News",
          "id": "per_01j954try4bd0jk4pfmxk2z1bd",
          "kind": "creator",
          "relationLabel": null
        },
        "publishedAt": "2026-10-16T03:00:00.000Z",
        "seen": true,
        "source": "server",
        "summary": null,
        "summaryLocale": null,
        "text": "Example headline for testing link cards.",
        "url": "https://truthsocial.com/@realexample/113000000000000001"
      },
      "type": "moment"
    },
    {
      "type": "caught_up",
      "unseenRemaining": 0
    }
  ],
  "generatedAt": "2026-10-17T09:00:00.000Z",
  "nextCursor": null,
  "seed": "fS33dDemo"
}