Skip to main content

Check Organization Balance

Check whether your organization has an active subscription and available credits before sending messages.

Endpoint​

GET /api/v1/agents/check-balance

Authentication​

This endpoint requires API key authentication. Include your API key in the Authorization header using the Bearer scheme.

Header Format:

Authorization: Bearer {PUBLIC_KEY}:{SECRET_KEY}

Request​

Headers​

HeaderTypeRequiredDescription
AuthorizationstringYesYour API key in the format Bearer pk_xxx:sk_xxx

Query Parameters​

This endpoint does not accept any query parameters.

Response​

Success Response​

Status Code: 200 OK

Response Body (has credits):

{
  "success": true,
  "organizationId": "org-550e8400-e29b-41d4-a716-446655440000",
  "hasCredits": true,
  "hasAssistant": true
}

Response Body (no credits):

{
  "success": true,
  "organizationId": "org-550e8400-e29b-41d4-a716-446655440000",
  "hasCredits": false,
  "hasAssistant": true
}

Response Body (no active subscription):

{
  "success": false,
  "hasCredits": false,
  "hasAssistant": false,
  "message": "No active subscription found for this organization"
}

Response Fields​

FieldTypeDescription
successbooleanWhether the check completed successfully
organizationIdstringThe organization ID associated with the API key
hasCreditsbooleanWhether the organization has credits remaining
hasAssistantbooleanWhether the organization has an AI assistant configured
messagestringError or status message (present when success is false)

Error Responses​

401 Unauthorized​

{
  "success": false,
  "message": "Organization ID not found in request"
}

404 Not Found​

{
  "success": false,
  "message": "Agent not found or unauthorized"
}

500 Internal Server Error​

{
  "success": false,
  "message": "Internal server error"
}

Example Usage​

cURL​

curl -X GET https://agentsgt.com/api/v1/agents/check-balance \
  -H "Authorization: Bearer pk_1234567890abcdef:sk_abcdef1234567890"

JavaScript (Fetch API)​

const publicKey = 'pk_1234567890abcdef';
const secretKey = 'sk_abcdef1234567890';

fetch('https://agentsgt.com/api/v1/agents/check-balance', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${publicKey}:${secretKey}`,
    'Content-Type': 'application/json'
  }
})
  .then(response => response.json())
  .then(data => {
    if (data.hasCredits) {
      console.log('Credits available - ready to send messages');
    } else {
      console.log('No credits remaining - please top up');
    }
  })
  .catch(error => {
    console.error('Error:', error);
  });

Python (Requests)​

import requests

public_key = 'pk_1234567890abcdef'
secret_key = 'sk_abcdef1234567890'

headers = {
    'Authorization': f'Bearer {public_key}:{secret_key}',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://agentsgt.com/api/v1/agents/check-balance',
    headers=headers
)

if response.status_code == 200:
    data = response.json()
    if data['hasCredits']:
        print('Credits available - ready to send messages')
    else:
        print('No credits remaining - please top up')
else:
    print(f"Error: {response.status_code} - {response.json()}")

Node.js (Axios)​

const axios = require('axios');

const publicKey = 'pk_1234567890abcdef';
const secretKey = 'sk_abcdef1234567890';

axios.get('https://agentsgt.com/api/v1/agents/check-balance', {
  headers: {
    'Authorization': `Bearer ${publicKey}:${secretKey}`,
    'Content-Type': 'application/json'
  }
})
  .then(response => {
    const { hasCredits, hasAssistant } = response.data;
    console.log(`Credits available: ${hasCredits}`);
    console.log(`Assistant configured: ${hasAssistant}`);
  })
  .catch(error => {
    console.error('Error:', error.response?.data || error.message);
  });

Notes​

  • Use this endpoint to check credit availability before sending messages to avoid 402 errors
  • The hasAssistant field indicates whether the organization has configured an OpenAI assistant for file search capabilities
  • A 200 response with success: false indicates no active subscription rather than a request error
  • This is a lightweight endpoint that does not consume credits