---
title: "retrieve instance"
method: GET
path: "/instances/{id}"
tags: ["instances"]
---

# retrieve instance

`GET /instances/{id}`

## Request

- Base URL: `https://waapi.app/api/v1`
- URL: `https://waapi.app/api/v1/instances/{id}`
- Auth: HTTP bearer

Retrieve a single instance by its ID

## Path parameters

- `id` integer, required

## Response `200`

JSON representation of your instance

- object
  - `instance` Instance
    - `id` integer
    - `name` string
    - `owner` string
    - `webhook_url` string
    - `webhook_events` EventType[]
    - `call_policy` CallPolicy, nullable: How the instance handles incoming calls. `null` or mode `ignore` means the call webhook fires and nothing else. Two requirements the schema cannot express: reject_with_message requires message, and answer_and_play requires audio_url or video_url — without them the request is answered with a 422.
      - `mode` 'ignore' | 'reject' | 'reject_with_message' | 'answer_and_play', required
      - `message` string, nullable: Text sent to the caller after rejecting (mode reject_with_message)
      - `audio_url` string, uri, nullable: wav, mp3 or ogg played into the call (mode answer_and_play), max 25 MB
      - `video_url` string, uri, nullable: mp4 (H.264) looped as the camera on video calls (mode answer_and_play), max 25 MB
      - `hangup_after_seconds` integer: Hang up at the latest this many seconds after the call connected (mode answer_and_play)
    - `send_protection` SendProtection: Send protection of this instance. Read-only: the switch is on the instance page in your account. While enabled, the instance sends one message at a time with a short pause, and conversations with recipients who have never written to this account are limited per hour and per day. A send over a limit is answered with HTTP 429 and a Retry-After header; nothing is sent. A fire-and-forget send is accepted with 202 and a refusal is read from GET /instances/{id}/request/{reference}.
      - `enabled` boolean
      - `disableable` boolean: false on trial instances, where the protection is always on.
    - `is_trial` boolean
  - `status` 'success' | 'error'

## Other responses

- `401`: Unauthorized — invalid or missing bearer token
- `403`: Forbidden — insufficient permissions or account blocked
- `404`: Not found — instance does not exist or does not belong to you
- `409`: Conflict — instance is not ready
- `422`: Validation error — invalid or missing request parameters
- `429`: Too many requests — rate limit exceeded

---

[API](https://skmtc.dev/waapi/apis/waapi-api-2.md) · [All operations](https://skmtc.dev/waapi/apis/waapi-api-2/llms.txt) · [OpenAPI document](https://skmtc.dev/waapi/apis/waapi-api-2/revisions/490302f75576?raw)