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

# Check one number

> GET /v1/instances/{id}/status — the live connection state of one number.

Checks the connection **live** and updates our stored record to match.

## Notes

* Use this before a batch run, or right after a send returned `409 instance_not_connected`, to confirm whether the number is really down.
* It costs one upstream check, so it is slower than [`GET /v1/instances`](/api-reference/instances/list). Do not call it in a tight loop for every message — check once before the batch.
* `phone_number` is learned the first time we see the number connected, so it may be `null` on a number that has never paired.
* If it turns out the same WhatsApp number is already connected on another of your instances, this returns `409 number_already_connected` — the session that was already up keeps working.

**Status values**

| `status`     | `connected` | Meaning                                                   |
| ------------ | ----------- | --------------------------------------------------------- |
| `open`       | `true`      | Connected and able to send.                               |
| `connecting` | `false`     | Pairing in progress — a QR is on screen or being scanned. |
| `close`      | `false`     | Not connected. Someone has to re-scan.                    |

## Example

```bash cURL theme={null}
curl https://api.bulkneo.com/v1/instances/YOUR_INSTANCE_ID/status \
  -H "apikey: YOUR_API_KEY"
```

```javascript Node.js — check before a batch theme={null}
const res = await fetch(
  `https://api.bulkneo.com/v1/instances/${instanceId}/status`,
  { headers: { apikey: process.env.BULKNEO_API_KEY } },
);
const { data } = await res.json();

if (!data.connected) {
  await alertOps(`${data.label} is ${data.status} — nothing will send until it is re-scanned`);
  return;
}
```

<Note>
  If the messaging service cannot be reached, this returns `502 upstream_unavailable` rather than guessing. That means "we do not know", not "your number is down".
</Note>


## OpenAPI

````yaml api-reference/openapi.json GET /v1/instances/{id}/status
openapi: 3.1.0
info:
  title: BulkNeo WhatsApp API
  version: 1.0.0
  description: >-
    Send WhatsApp messages from your own connected numbers. Every request is
    authenticated with an `apikey` header and names the `instance_id` of the
    number it should be sent from.
servers:
  - url: https://api.bulkneo.com
    description: BulkNeo API
security:
  - apikey: []
tags:
  - name: Messages
    description: Send a message from one of your connected numbers.
  - name: Numbers
    description: Check which numbers are reachable on WhatsApp.
  - name: Instances
    description: Create, connect, inspect and remove your WhatsApp numbers.
  - name: Service
    description: Unauthenticated service health checks.
paths:
  /v1/instances/{id}/status:
    get:
      tags:
        - Instances
      summary: Check one number, live
      description: >-
        Checks the live connection state of one number and updates our stored
        record to match. Use this before a batch send, or when a send has just
        returned `409 instance_not_connected`.
      operationId: getInstanceStatus
      parameters:
        - $ref: '#/components/parameters/InstanceIdPath'
      responses:
        '200':
          description: Live status.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    const: true
                  data:
                    type: object
                    properties:
                      instance_id:
                        type: string
                        format: uuid
                      label:
                        type:
                          - string
                          - 'null'
                      status:
                        $ref: '#/components/schemas/ConnectionStatus'
                      connected:
                        type: boolean
                      phone_number:
                        type:
                          - string
                          - 'null'
                  request_id:
                    type: string
                    format: uuid
              example:
                success: true
                data:
                  instance_id: 3f9c1a2b-7d4e-4c81-9f0a-2b6d5e8c1a34
                  label: Sales
                  status: open
                  connected: true
                  phone_number: '919876543210'
                request_id: b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/InstanceNotFound'
        '409':
          $ref: '#/components/responses/DuplicateNumber'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
components:
  parameters:
    InstanceIdPath:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: The `instance_id` of one of your numbers.
      example: 3f9c1a2b-7d4e-4c81-9f0a-2b6d5e8c1a34
  schemas:
    ConnectionStatus:
      type: string
      description: >-
        `open` connected and able to send, `connecting` pairing in progress,
        `close` not connected.
      example: open
    Error:
      type: object
      properties:
        success:
          type: boolean
          const: false
        error:
          type: object
          properties:
            code:
              type: string
              description: >-
                Stable machine-readable code. Branch on this, not on the
                message.
            message:
              type: string
              description: Human-readable explanation. The wording may change.
            details:
              type: object
              description: Extra safe context, present on some errors.
        request_id:
          type: string
          format: uuid
          description: Quote this when asking support about a request.
  responses:
    BadRequest:
      description: >-
        `invalid_request` a field is missing or malformed (the message names it,
        including its position in a list) · `invalid_media_url` the `url` is not
        a public http(s) link to a file.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: invalid_request
              message: Field "text" is required and must be a non-empty string.
            request_id: b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
    Unauthorized:
      description: >-
        `missing_api_key` no `apikey` header was sent · `invalid_api_key` the
        key is unknown or revoked.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: invalid_api_key
              message: Invalid or revoked API key.
            request_id: b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
    Forbidden:
      description: >-
        `account_suspended` · `access_expired` · `trial_quota_exceeded` ·
        `instance_limit_reached` · `activation_unavailable`.


        On `instance_limit_reached`, `details.limit_source` tells you which cap
        you hit: `plan` (the plan you are on — upgrade it) or `account` (a cap
        set on your account — ask your provider to raise it). Branch on that,
        never on the wording of the message.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: trial_quota_exceeded
              message: >-
                Trial message quota reached (500 messages). Upgrade to a paid
                plan to keep sending.
              details:
                trial_message_limit: 500
            request_id: b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
    InstanceNotFound:
      description: >-
        `instance_not_found` — no such instance on your account. The same answer
        is given for an id that does not exist and one that belongs to someone
        else.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: instance_not_found
              message: >-
                Instance not found. Check the instance_id and that it belongs to
                your account.
            request_id: b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
    DuplicateNumber:
      description: >-
        `number_already_connected` — this WhatsApp number is already connected
        on another of your instances.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: number_already_connected
              message: >-
                This WhatsApp number is already connected on another of your
                instances. Disconnect it there first, or scan a different
                number.
            request_id: b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
    RateLimited:
      description: >-
        `rate_limit_exceeded` — too many requests this minute. Wait for the
        number of seconds in the `Retry-After` header. `details.scope` and the
        `X-RateLimit-Scope` header say WHICH allowance you exceeded.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
        X-RateLimit-Scope:
          $ref: '#/components/headers/RateLimitScope'
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: rate_limit_exceeded
              message: Rate limit exceeded, retry in 12s.
              details:
                retry_after_seconds: 12
                limit_per_minute: 20
                scope: messages
            request_id: b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
    InternalError:
      description: >-
        `internal_error` — something went wrong on our side. Quote the
        `request_id` to support.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: internal_error
              message: An unexpected error occurred.
            request_id: b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
    UpstreamUnavailable:
      description: >-
        `upstream_unavailable` — the messaging service is temporarily
        unavailable. Safe to retry after a short pause.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: upstream_unavailable
              message: >-
                The messaging service is temporarily unavailable. Please retry
                shortly.
            request_id: b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
  headers:
    RateLimitScope:
      description: >-
        WHICH allowance the other X-RateLimit-* headers describe. `messages`
        covers every /v1/messages/* endpoint and /v1/numbers/check together;
        `instances` is the separate, much larger budget for /v1/instances/*. If
        you cache a limit, cache it against its scope.
      schema:
        type: string
        enum:
          - messages
          - instances
      example: messages
    RateLimitLimit:
      description: Requests allowed per minute on this scope.
      schema:
        type: integer
      example: 20
    RateLimitRemaining:
      description: Requests left in the current minute on this scope.
      schema:
        type: integer
      example: 17
    RateLimitReset:
      description: >-
        Seconds until the allowance next goes up by one. Present on successful
        responses too, so you can pace yourself without first earning a 429. The
        window is a rolling minute, so this is when the oldest request ages out
        — not a fixed reset instant. If `X-RateLimit-Remaining` is above 0 you
        can send now.
      schema:
        type: integer
      example: 43
  securitySchemes:
    apikey:
      type: apiKey
      in: header
      name: apikey
      description: >-
        Your API key, sent in an `apikey` request header. Never in the URL,
        never as a Bearer token.

````