Skip to content

leaseAgentTasks

POST
/agent/tasks/lease
curl --request POST \
  --url http://localhost:8080/api/v1/agent/tasks/lease \
  --header 'Content-Type: application/json' \
  --cookie hs_session=<hs_session> \
  --data '{ "limit": 5, "platforms": [ "instagram" ], "agentVersion": "example" }'

Claims up to limit due tasks for 10 minutes. Respects per-platform hourly caps and the token’s platform list. Returns an empty list when nothing is due; the response says when to ask again.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
limit
integer
default: 5 >= 1 <= 20
platforms

Only lease tasks for these platforms (e.g. the ones the agent’s browser is logged into).

Array<string>
Allowed values: instagram facebook line wechat bluesky x douyin xiaohongshu truthsocial
agentVersion
string
<= 60 characters

Responses

Section titled “Responses”

200

Section titled “200”

Leased tasks.

Media typeapplication/json
object
tasks
required
Array<object>
object
id
required
string
/^[a-z]{2,3}_[0-9a-hjkmnp-tv-z]{26}$/
kind
required
string
Allowed values: fetch lookup
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
platformUserId
string | null
profileUrl
required
string format: uri
personName
required
string
since
One of:
string format: date-time
knownItemIds

Up to 50 most recent platform item IDs already stored; skip these.

Array<string>
wantKinds
Array<string>
Allowed values: story post video link text
maxItems
integer
default: 20
instructions
required

Short platform playbook key, e.g. “instagram.fetch.v1” (see agents/skills/homestead/references/platforms.md).

string
leaseExpiresAt
required
string format: date-time
attempts
required
integer
retryAfterSeconds
required

When to lease again if tasks is empty or after finishing these.

integer

Examples

Exampleseed

Derived from fixtures/seed.json.

{
  "retryAfterSeconds": 300,
  "tasks": [
    {
      "account": {
        "handle": "lin.cooks",
        "id": "acc_01j9te0skfktnnmw6zvew46azb",
        "personName": "Lin",
        "platform": "instagram",
        "platformUserId": "",
        "profileUrl": "https://www.instagram.com/lin.cooks/"
      },
      "attempts": 0,
      "id": "tsk_01j9a1b2c3d4e5f6g7h8j9k02t",
      "instructions": "instagram.fetch.v1",
      "kind": "fetch",
      "knownItemIds": [
        "C9xYzAbCdEg",
        "C9xYzAbCdEf"
      ],
      "leaseExpiresAt": "2026-10-17T09:10:00.000Z",
      "maxItems": 20,
      "since": "2026-10-17T08:00:00.000Z",
      "wantKinds": [
        "story",
        "post",
        "video"
      ]
    },
    {
      "account": {
        "handle": "somsak_runs",
        "id": "acc_01j9dfpvstm7aq628gwwc9xkq3",
        "personName": "Somsak",
        "platform": "x",
        "platformUserId": "",
        "profileUrl": "https://x.com/somsak_runs"
      },
      "attempts": 1,
      "id": "tsk_01j9a1b2c3d4e5f6g7h8j9k02v",
      "instructions": "x.fetch.v1",
      "kind": "fetch",
      "knownItemIds": [],
      "leaseExpiresAt": "2026-10-17T09:10:00.000Z",
      "maxItems": 20,
      "since": null,
      "wantKinds": [
        "post",
        "video",
        "link"
      ]
    }
  ]
}