> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracklysms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Agent Setup Status

> Poll setup with its limited status token; credentials are configured separately.

Reads a request created by [Start Agent Account Setup](/api-reference/v2/agent-onboarding/create). Send its `poll_token` as `Authorization: Bearer <poll_token>`. This endpoint does not use `X-Api-Key`.

Status reads work before signup or login; the matching bearer capability is their authentication boundary. The token cannot verify an email, log in, approve a message, connect an account by itself, or retrieve an API key.

## Parameters

<ParamField path="intent_id" type="string" required>32-character setup identifier returned at creation.</ParamField>

<ParamField header="Authorization" type="string" required>
  `Bearer <poll_token>` from creation. Use it only for this setup request.
</ParamField>

## Response Fields

<ResponseField name="onboarding.id" type="string">Setup identifier.</ResponseField>
<ResponseField name="onboarding.status" type="string">`pending`, `completed`, or `expired`.</ResponseField>
<ResponseField name="onboarding.name" type="string">Required business account name.</ResponseField>
<ResponseField name="onboarding.expires_at" type="string">Current confirmation deadline in UTC.</ResponseField>
<ResponseField name="onboarding.account_id" type="integer">Connected account after completion; otherwise null.</ResponseField>
<ResponseField name="onboarding.next_step" type="string">`complete_signup` before completion; `configure_api_key` afterward.</ResponseField>

Responses omit the email and all account credentials and use `Cache-Control: no-store`. A retained expired request returns 200 with `status: expired`; retention ends one day after the original request.

Poll with a bound. Limits are 60 authenticated status reads per setup request per minute and 1,000 attempts per IP per minute. Invalid capabilities do not consume the request's status budget. Respect `Retry-After` on 429.

## Browser confirmation and recovery

The original Trackly setup page requires both a signed-in direct-owner session and the status capability for confirmation or renewal. The verified email, new account name, self-pay/free account eligibility, and any required two-step verification must still match. Public polling cannot perform these actions.

The owner confirmation action uses `POST /auth/agent-onboarding/<id>/confirm` with an empty JSON object. It connects only the eligible new account. If the one-hour deadline expires, the owner renewal action uses `POST /auth/agent-onboarding/<id>/renew`, also with an empty object and the same capability. These are authenticated dashboard routes, not anonymous External API endpoints.

Renewal keeps the original identity, account eligibility start time, parent, and one-day retention deadline. It extends an expired pending request by at most one hour, never past retention. An unexpired request is unchanged; a completed request cannot be renewed. Confirmation and renewal share a 10-attempt-per-owner-per-minute limit.

After retention, renewal returns expired while the record remains, or not found after removal. Contact support to recover an already-created account; do not start duplicate signup to work around expiry.

After `completed`, create a sandbox confirmation-required API key in Trackly and configure it privately in the MCP client. No setup response returns or installs the key.

## Errors

| HTTP | Code                       | Meaning                                                       |
| ---- | -------------------------- | ------------------------------------------------------------- |
| 401  | `onboarding_invalid_token` | Missing or malformed bearer capability.                       |
| 404  | `onboarding_not_found`     | Unknown identifier, unmatched capability, or removed request. |
| 429  | `onboarding_rate_limited`  | Poll limit reached; obey `Retry-After`.                       |
| 503  | `onboarding_unavailable`   | Status could not be read safely.                              |

Dashboard confirmation/renewal can additionally return `onboarding_identity_required` or `onboarding_owner_required` (403), `onboarding_account_ineligible`, `onboarding_changed`, or `onboarding_expired` (409), and temporary setup/factor errors. Resolve them in the original setup tab.

## Example

<RequestExample>
  ```bash cURL theme={null}
  curl https://api.tracklysms.com/api/v2/agent-onboarding/0123456789abcdef0123456789abcdef \
    -H "Authorization: Bearer poll_token_from_creation"
  ```
</RequestExample>

<ResponseExample>
  ```json Completed (200) theme={null}
  {
    "onboarding": {
      "id": "0123456789abcdef0123456789abcdef",
      "status": "completed",
      "name": "Example Pizza",
      "expires_at": "2026-09-04T15:00:00Z",
      "account_id": 1042,
      "next_step": "configure_api_key"
    }
  }
  ```
</ResponseExample>