List your numbers

curl --request GET \
  --url https://api.bulkneo.com/v1/instances \
  --header 'apikey: <api-key>'

const options = {method: 'GET', headers: {apikey: '<api-key>'}};

fetch('https://api.bulkneo.com/v1/instances', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": true,
  "data": {
    "slots": {
      "kind": "direct",
      "used": 2,
      "limit": null,
      "billed": false
    },
    "instances": [
      {
        "instance_id": "3f9c1a2b-7d4e-4c81-9f0a-2b6d5e8c1a34",
        "label": "Sales",
        "status": "open",
        "connected": true,
        "phone_number": "919876543210",
        "last_connected": "2026-08-08T09:14:22.000Z",
        "created_at": "2026-07-21T06:02:11.000Z"
      },
      {
        "instance_id": "a1b7c3d9-2e4f-4a60-b8c1-5d7e9f0a2b34",
        "label": "Support",
        "status": "close",
        "connected": false,
        "phone_number": "919812345678",
        "last_connected": "2026-08-06T18:40:03.000Z",
        "created_at": "2026-07-24T11:31:47.000Z"
      }
    ]
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

{
  "success": false,
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid or revoked API key."
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

{
  "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"
}

{
  "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"
}

{
  "success": false,
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred."
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

GET

instances

List your numbers

curl --request GET \
  --url https://api.bulkneo.com/v1/instances \
  --header 'apikey: <api-key>'

const options = {method: 'GET', headers: {apikey: '<api-key>'}};

fetch('https://api.bulkneo.com/v1/instances', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": true,
  "data": {
    "slots": {
      "kind": "direct",
      "used": 2,
      "limit": null,
      "billed": false
    },
    "instances": [
      {
        "instance_id": "3f9c1a2b-7d4e-4c81-9f0a-2b6d5e8c1a34",
        "label": "Sales",
        "status": "open",
        "connected": true,
        "phone_number": "919876543210",
        "last_connected": "2026-08-08T09:14:22.000Z",
        "created_at": "2026-07-21T06:02:11.000Z"
      },
      {
        "instance_id": "a1b7c3d9-2e4f-4a60-b8c1-5d7e9f0a2b34",
        "label": "Support",
        "status": "close",
        "connected": false,
        "phone_number": "919812345678",
        "last_connected": "2026-08-06T18:40:03.000Z",
        "created_at": "2026-07-24T11:31:47.000Z"
      }
    ]
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

{
  "success": false,
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid or revoked API key."
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

{
  "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"
}

{
  "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"
}

{
  "success": false,
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred."
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

The quickest way to find an instance_id in code, and a cheap health check for a dashboard.

Notes

Returns every number on the account that has not been deleted, oldest first.
connected is the field to read: true means that number can send right now.
This returns the stored status, not a fresh check of the live connection. It is fast and costs nothing. To force a live check of one number, use GET /v1/instances/{id}/status.
phone_number is filled in once the number has been observed connected. It can be null on a number that has never connected.
last_connected is the last time the connection was observed open — it moves whenever something checks, so treat it as “seen recently”, not as a session start time.
slots summarises how many numbers you are using and what your account allows. limit is null when there is no fixed cap. If the summary cannot be worked out, slots is null and the list itself is still correct.

Example

curl https://api.bulkneo.com/v1/instances \
  -H "apikey: YOUR_API_KEY"

const res = await fetch("https://api.bulkneo.com/v1/instances", {
  headers: { apikey: process.env.BULKNEO_API_KEY },
});

const { data } = await res.json();
for (const i of data.instances) {
  console.log(i.label, i.instance_id, i.connected ? "ready" : "DISCONNECTED");
}

import os
import requests

res = requests.get(
    "https://api.bulkneo.com/v1/instances",
    headers={"apikey": os.environ["BULKNEO_API_KEY"]},
    timeout=30,
)
res.raise_for_status()

for i in res.json()["data"]["instances"]:
    print(i["label"], i["instance_id"], "ready" if i["connected"] else "DISCONNECTED")

This is also the cheapest way to test that an API key works — it sends nothing and uses no message allowance.

Authorizations

apikey

string

header

required

Your API key, sent in an apikey request header. Never in the URL, never as a Bearer token.

Response

Your numbers.

success

boolean

data

object

Show child attributes

request_id

string<uuid>

⌘I

Overview

Messages

Numbers

Instances

Service

List your numbers

Notes

Example

Authorizations

Response

​Notes

​Example

Authorizations

Response

Notes

Example