---
title: "GET /provisioning-requests"
method: GET
path: "/provisioning-requests"
---

# GET /provisioning-requests

`GET /provisioning-requests`

## Request

- Base URL: `https://api.useanima.sh/v1`
- URL: `https://api.useanima.sh/v1/provisioning-requests`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

## Query parameters

- `cursor` string: Opaque cursor from a previous response to fetch the next page
- `limit` integer: Maximum number of items to return per page (1–100, default 20)
- `agentId` union: Agent identifier. Optional when using an agent API key (resolved automatically); required when using a master key.
  - string
  - string
- `status` 'PENDING' | 'APPROVED' | 'DECLINED' | 'EXPIRED' | 'CANCELLED': Filter by lifecycle status
- `resource` 'VAULT' | 'PHONE_NUMBER' | 'GENERIC': Filter by requested resource

## Response `200`

OK

- object: Paginated provisioning requests
  - `items` object[], required
    - `requestId` string, required: Unique provisioning request identifier
    - `agentId` string, required: Agent the resource would belong to
    - `agentName` string, required: Agent display name, so the owner knows who is asking
    - `resource` 'VAULT' | 'PHONE_NUMBER' | 'GENERIC', required: Resource being requested: VAULT (encrypted secret storage for this agent), PHONE_NUMBER (a provisioned number, Starter+ only), or GENERIC (a master-gated operation the agent tried to perform; approving grants permission rather than provisioning anything).
    - `reason` string, required: The agent's stated justification
    - `status` 'PENDING' | 'APPROVED' | 'DECLINED' | 'EXPIRED' | 'CANCELLED', required: Lifecycle status: PENDING (awaiting the owner), APPROVED (resource provisioned), DECLINED (owner refused — soft, the agent may ask again), EXPIRED (7-day TTL elapsed unanswered), CANCELLED (withdrawn by the agent).
    - `options` object, nullable, required: Resource-specific options; ignored for resources that take none
      - `countryCode` string: PHONE_NUMBER: ISO 3166-1 alpha-2 country code, e.g. 'US'
      - `areaCode` string: PHONE_NUMBER: preferred 3-digit area code; any is used if unavailable
    - `permission` object, nullable, required: Present only on a permission request; null on a resource provisioning request
      - `procedurePath` string, required: The master-gated procedure the agent tried to run, dotted — 'agent.delete'
      - `readOnly` boolean, required: Whether the procedure is read-only. Derived from the contract's HTTP method on the server so a client never re-derives it, and it is what makes Bypass applicable.
      - `argumentPreview` object, nullable, required: Redacted sketch of the call's arguments. Null — rather than empty — when the input was not an object, so 'nothing to show' stays distinguishable from 'shown and empty'.
    - `expiresAt` string, date-time, required: When an unanswered request stops being actionable
    - `decidedAt` string, date-time, nullable, required: When the owner decided; null while PENDING
    - `decidedNote` string, nullable, required: The owner's note, typically the reason for a decline — surfaced so a second attempt can address the objection instead of repeating the first
    - `provisionedId` string, nullable, required: Id of what approval created (vault identity or phone identity); null unless APPROVED
    - `createdAt` string, date-time, required: When the agent asked
  - `pagination` object, required: Pagination metadata returned with list responses
    - `nextCursor` string, nullable, required: Cursor to pass as the `cursor` parameter to retrieve the next page, or null if no more results
    - `hasMore` boolean, required: Whether additional pages of results are available

---

[API](https://skmtc.dev/useanima/apis/anima-api.md) · [All operations](https://skmtc.dev/useanima/apis/anima-api/llms.txt) · [OpenAPI document](https://skmtc.dev/useanima/apis/anima-api/revisions/aaa148188980?raw)