cURL (Windows)
curl "https://api.bulkneo.com/v1/instances/YOUR_INSTANCE_ID/status" -H "apikey: YOUR_API_KEY"const options = {method: 'GET', headers: {apikey: '<api-key>'}};
fetch('https://api.bulkneo.com/v1/instances/{id}/status', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.bulkneo.com/v1/instances/{id}/status"
headers = {"apikey": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text){
"success": true,
"data": {
"instance_id": "3f9c1a2b-7d4e-4c81-9f0a-2b6d5e8c1a34",
"label": "Sales",
"status": "open",
"connected": true,
"phone_number": "919000000000"
},
"request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}{
"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"
}{
"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": "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"
}{
"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"
}{
"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"
}{
"success": false,
"error": {
"code": "upstream_unavailable",
"message": "The messaging service is temporarily unavailable. Please retry shortly."
},
"request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}Instances
Check one number
GET /v1/instances/{id}/status — the live connection state of one number.
GET
/
v1
/
instances
/
{id}
/
status
cURL (Windows)
curl "https://api.bulkneo.com/v1/instances/YOUR_INSTANCE_ID/status" -H "apikey: YOUR_API_KEY"const options = {method: 'GET', headers: {apikey: '<api-key>'}};
fetch('https://api.bulkneo.com/v1/instances/{id}/status', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.bulkneo.com/v1/instances/{id}/status"
headers = {"apikey": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text){
"success": true,
"data": {
"instance_id": "3f9c1a2b-7d4e-4c81-9f0a-2b6d5e8c1a34",
"label": "Sales",
"status": "open",
"connected": true,
"phone_number": "919000000000"
},
"request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}{
"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"
}{
"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": "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"
}{
"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"
}{
"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"
}{
"success": false,
"error": {
"code": "upstream_unavailable",
"message": "The messaging service is temporarily unavailable. Please retry shortly."
},
"request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}The playground on this page is live. There is no test mode and no sandbox: pressing Send authenticates with the key you paste and really calls
https://api.bulkneo.com — a send delivers a real WhatsApp message to the number you type, and an instance call really changes your account. Use your own number while you are exploring, and paste a key only from a machine you trust.Your browser remembers what you type into the playground, so a key you paste here is still in the Authorization box on your next visit. Nobody else sees it — it never leaves your machine and it is not part of this site — but on a shared or borrowed computer, clear the site data when you are done.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. Do not call it in a tight loop for every message — check once before the batch. phone_numberis learned the first time we see the number connected, so it may benullon 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 | 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
curl https://api.bulkneo.com/v1/instances/YOUR_INSTANCE_ID/status \
-H "apikey: YOUR_API_KEY"
curl "https://api.bulkneo.com/v1/instances/YOUR_INSTANCE_ID/status" -H "apikey: YOUR_API_KEY"
Node.js — check before a batch
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;
}
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”.
