---
title: "The single next move for this caller, with the command that executes it."
method: GET
path: "/next"
---

# The single next move for this caller, with the command that executes it.

`GET /next`

## Request

- Base URL: `https://forbiz.io/api/public/agent`
- URL: `https://forbiz.io/api/public/agent/next`
- Auth: HTTP bearer

Returns EXACTLY ONE item — the top of the existing attention ranking; no new scoring model exists here. `actor` says who owns the move: for an agent item, `command` is taken from the action's timing.available_commands and is executable as-is once body_template is filled; for a human item, `for_human` says what to look at and why, and an agent executing it would be recording work it did not do. `handoff` is what a successor agent needs to continue without reading the history. When nothing is pending, `rank` is null and `message` explains that in one sentence.

## Response `200`

Next move

- object
  - `rank` integer, nullable
  - `reason` string
  - `actor` 'agent' | 'human'
  - `command` object
    - `method` string
    - `path` string
    - `body_template` object
  - `for_human` object
    - `what_to_look_at` string
    - `why` string
  - `context` object
    - `action_id` string
    - `project_id` string, nullable
    - `due_at` string, nullable
    - `governing_due_at` string, nullable
    - `expected_signal_at` string, nullable
  - `handoff` object
    - `last_human_touch` object, nullable
    - `last_signal` object, nullable
  - `also_pending` integer
  - `message` string

## Other responses

- `409`: This credential is not bound to a workspace

---

[API](https://skmtc.dev/forbiz/apis/forbiz-external-agent-api.md) · [All operations](https://skmtc.dev/forbiz/apis/forbiz-external-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/forbiz/apis/forbiz-external-agent-api/revisions/e5b10d59dc5f?raw)