Skip to content

startUpdateRun

POST
/circles/{circleId}/update-runs
curl --request POST \
  --url http://localhost:8080/api/v1/circles/per_01j9x3k8m2q4r5s6t7v8w9y0z1/update-runs \
  --cookie hs_session=<hs_session>

Starts “Update circle” for the extension: returns the capturable accounts in the circle (max 30) in the order to open them (least recently captured first). Accounts on closed platforms are listed with action visit_only.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
circleId
required
string
/^[a-z]{2,3}_[0-9a-hjkmnp-tv-z]{26}$/

Responses

Section titled “Responses”

201

Section titled “201”

Run created.

Media typeapplication/json
object
id
required
string
/^[a-z]{2,3}_[0-9a-hjkmnp-tv-z]{26}$/
circle
required
object
id
required
string
/^[a-z]{2,3}_[0-9a-hjkmnp-tv-z]{26}$/
name
required
string
color
required
string
Allowed values: terracotta honey sage dusk plum clay
member
object
id
required
string
/^[a-z]{2,3}_[0-9a-hjkmnp-tv-z]{26}$/
displayName
required
string
avatar
One of:
object
id
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
status
required
string
Allowed values: running processing completed stopped
startedAt
required
string format: date-time
finishedAt
One of:
string format: date-time
items
required
Array<object>
<= 60 items
object
account
required
object
id
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
person
required
object
id
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
id
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
action
required
string
Allowed values: open visit_only
status
required
string
Allowed values: waiting opening capturing uploaded processing done skipped failed
captureId
One of:
string
/^[a-z]{2,3}_[0-9a-hjkmnp-tv-z]{26}$/
newMoments
integer
pageState
string | null
Allowed values: ok login_wall not_found blocked empty unrelated
detail
string | null
totals
required
object
accounts
required
integer
done
required
integer
skipped
required
integer
failed
required
integer
newMoments
required
integer
people
required

People with at least one new moment.

integer
homesteadUrl

Link for “See them in Homestead”.

string format: uri

Examples

Exampleseed

Derived from fixtures/seed.json.

{
  "circle": {
    "color": "terracotta",
    "id": "cir_01j9kaptqa5dcqne4nmnrbp86d",
    "name": "Family"
  },
  "finishedAt": null,
  "id": "run_01j9a1b2c3d4e5f6g7h8j9k01j",
  "items": [
    {
      "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/"
      },
      "action": "open",
      "captureId": null,
      "detail": null,
      "newMoments": 0,
      "pageState": null,
      "person": {
        "avatar": null,
        "closeness": 1,
        "displayName": "Mom",
        "id": "per_01j9wst6a8vjc69r66y6fj70t5",
        "kind": "family",
        "relationLabel": "แม่"
      },
      "status": "waiting"
    },
    {
      "account": {
        "deepLinks": {
          "android": "fb://profile/",
          "ios": "fb://profile/",
          "web": "https://www.facebook.com/pranee.wong"
        },
        "displayName": null,
        "handle": "pranee.wong",
        "id": "acc_01j9wkspf8va1pwmaj7qwb7e1f",
        "platform": "facebook",
        "profileUrl": "https://www.facebook.com/pranee.wong"
      },
      "action": "open",
      "captureId": null,
      "detail": null,
      "newMoments": 0,
      "pageState": null,
      "person": {
        "avatar": null,
        "closeness": 1,
        "displayName": "Mom",
        "id": "per_01j9wst6a8vjc69r66y6fj70t5",
        "kind": "family",
        "relationLabel": "แม่"
      },
      "status": "waiting"
    },
    {
      "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/"
      },
      "action": "open",
      "captureId": null,
      "detail": null,
      "newMoments": 0,
      "pageState": null,
      "person": {
        "avatar": null,
        "closeness": 2,
        "displayName": "Lin",
        "id": "per_01j9f8r1agkh6g3jp30xcwnytc",
        "kind": "family",
        "relationLabel": "Cousin"
      },
      "status": "waiting"
    },
    {
      "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"
      },
      "action": "visit_only",
      "captureId": null,
      "detail": null,
      "newMoments": 0,
      "pageState": null,
      "person": {
        "avatar": null,
        "closeness": 1,
        "displayName": "Grandma Noi",
        "id": "per_01j9w5jqj9nm7gdsybfz53mcjr",
        "kind": "family",
        "relationLabel": "ยาย"
      },
      "status": "waiting"
    },
    {
      "account": {
        "deepLinks": {
          "android": "weixin://",
          "copyValue": "wei_chengdu88",
          "hintKey": "platformWechatOpenHint",
          "ios": "weixin://",
          "web": "https://weixin.qq.com/"
        },
        "displayName": null,
        "handle": "wei_chengdu88",
        "id": "acc_01j9e8wtqqwvx5c5qxjqyd78he",
        "platform": "wechat",
        "profileUrl": "https://weixin.qq.com/"
      },
      "action": "visit_only",
      "captureId": null,
      "detail": null,
      "newMoments": 0,
      "pageState": null,
      "person": {
        "avatar": null,
        "closeness": 2,
        "displayName": "Uncle Wei",
        "id": "per_01j9yjkch7a0ayzz8784jtf08t",
        "kind": "family",
        "relationLabel": "舅舅"
      },
      "status": "waiting"
    },
    {
      "account": {
        "deepLinks": {
          "android": "snssdk1128://user/profile/98765432101",
          "ios": "snssdk1128://user/profile/98765432101",
          "web": "https://www.douyin.com/user/MS4wLjABAAAAweichengdu0000000000000000000000"
        },
        "displayName": null,
        "handle": "MS4wLjABAAAAweichengdu0000000000000000000000",
        "id": "acc_01j936xmqyft8qfbq7srt9h04r",
        "platform": "douyin",
        "profileUrl": "https://www.douyin.com/user/MS4wLjABAAAAweichengdu0000000000000000000000"
      },
      "action": "open",
      "captureId": null,
      "detail": null,
      "newMoments": 0,
      "pageState": null,
      "person": {
        "avatar": null,
        "closeness": 2,
        "displayName": "Uncle Wei",
        "id": "per_01j9yjkch7a0ayzz8784jtf08t",
        "kind": "family",
        "relationLabel": "舅舅"
      },
      "status": "waiting"
    }
  ],
  "member": {
    "avatar": null,
    "displayName": "Mali",
    "id": "mem_01j9kt0d8rwgmhnmxkmv0frnr0"
  },
  "startedAt": "2026-10-17T08:40:00.000Z",
  "status": "running",
  "totals": {
    "accounts": 6,
    "done": 0,
    "failed": 0,
    "newMoments": 0,
    "people": 0,
    "skipped": 0
  }
}

404

Section titled “404”

Not found.

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
code
required
string
i18nKey
string
detail
string
fields
Array<object>
object
path
required
string
code
required
string
i18nKey
string

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "code": "example",
  "i18nKey": "example",
  "detail": "example",
  "fields": [
    {
      "path": "example",
      "code": "example",
      "i18nKey": "example"
    }
  ]
}

409

Section titled “409”

Conflicts with current state.

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
code
required
string
i18nKey
string
detail
string
fields
Array<object>
object
path
required
string
code
required
string
i18nKey
string

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "code": "example",
  "i18nKey": "example",
  "detail": "example",
  "fields": [
    {
      "path": "example",
      "code": "example",
      "i18nKey": "example"
    }
  ]
}