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

Header	Type	Required	Description
Authorization	string	Yes	Your 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

Field	Type	Description
success	boolean	Whether the check completed successfully
organizationId	string	The organization ID associated with the API key
hasCredits	boolean	Whether the organization has credits remaining
hasAssistant	boolean	Whether the organization has an AI assistant configured
message	string	Error 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

Related Endpoints

• Send Message - Send a message to an agent
• Chat - Start a streaming chat conversation
• Get Metrics by Organization - View detailed consumption metrics