Swarms API Documentation - Build AI Agents & Multi-Agent Systems

Retrieve your current API credit balance from the /v1/account/credits endpoint. This endpoint provides detailed information about all credit types associated with your account, including regular credits, free credits, referral credits, and the total available balance.

Credits are automatically deducted after each API request completes, drawing down free_credit first, then referral_credits, then credit (regular/purchased). Check your balance regularly to ensure you have sufficient credits for your operations.

Quick Start

Python
JavaScript
TypeScript
Rust
Go

import os
import json
import requests
from dotenv import load_dotenv

load_dotenv()

API_KEY = os.getenv("SWARMS_API_KEY")
BASE_URL = "https://api.swarms.world"

headers = {
    "x-api-key": API_KEY,
    "Content-Type": "application/json",
}

def get_credit_balance() -> dict | None:
    """Fetch current credit balance for the authenticated user."""
    resp = requests.get(f"{BASE_URL}/v1/account/credits", headers=headers)

    if resp.status_code == 200:
        return resp.json()

    print(f"Error: {resp.status_code} - {resp.text}")
    return None

if __name__ == "__main__":
    data = get_credit_balance()
    if data:
        print("✅ Credit balance retrieved successfully!")
        print(f"Total Credits: ${data.get('total_credits', 0):.2f}")
        print(f"Regular Credits: ${data.get('credit', 0):.2f}")
        print(f"Free Credits: ${data.get('free_credit', 0):.2f}")
        print(f"Referral Credits: ${data.get('referral_credits', 0):.2f}")
        print(json.dumps(data, indent=2))

const API_KEY = process.env.SWARMS_API_KEY;
const BASE_URL = "https://api.swarms.world";

const headers = {
    "x-api-key": API_KEY,
    "Content-Type": "application/json"
};

async function getCreditBalance() {
    try {
        const response = await fetch(`${BASE_URL}/v1/account/credits`, {
            method: 'GET',
            headers: headers
        });

        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }

        const data = await response.json();
        console.log("✅ Credit balance retrieved successfully!");
        console.log(`Total Credits: $${data.total_credits?.toFixed(2) || 0}`);
        console.log(`Regular Credits: $${data.credit?.toFixed(2) || 0}`);
        console.log(`Free Credits: $${data.free_credit?.toFixed(2) || 0}`);
        console.log(`Referral Credits: $${data.referral_credits?.toFixed(2) || 0}`);
        console.log(JSON.stringify(data, null, 2));
        
        return data;
    } catch (error) {
        console.error("Error fetching credit balance:", error);
        return null;
    }
}

getCreditBalance();

import 'dotenv/config'

const API_KEY = process.env.SWARMS_API_KEY
const BASE_URL = 'https://api.swarms.world'

if (!API_KEY) {
  throw new Error('SWARMS_API_KEY is not set')
}

interface CreditBalance {
  credit: number
  free_credit: number
  referral_credits: number
  total_credits: number
}

async function getCreditBalance(): Promise<CreditBalance | null> {
  const res = await fetch(`${BASE_URL}/v1/account/credits`, {
    method: 'GET',
    headers: {
      'x-api-key': API_KEY,
      'Content-Type': 'application/json',
    },
  })

  if (!res.ok) {
    const text = await res.text()
    throw new Error(`HTTP ${res.status}: ${text}`)
  }

  const data = (await res.json()) as CreditBalance
  console.log('✅ Credit balance retrieved successfully!')
  console.log(`Total Credits: $${data.total_credits.toFixed(2)}`)
  console.log(`Regular Credits: $${data.credit.toFixed(2)}`)
  console.log(`Free Credits: $${data.free_credit.toFixed(2)}`)
  console.log(`Referral Credits: $${data.referral_credits.toFixed(2)}`)
  
  return data
}

void getCreditBalance().catch(console.error)

use std::env;
use reqwest::blocking::Client;
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
struct CreditBalance {
    credit: f64,
    free_credit: f64,
    referral_credits: f64,
    total_credits: f64,
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_key = env::var("SWARMS_API_KEY")
        .expect("SWARMS_API_KEY environment variable is required");

    let client = Client::new();

    let response = client
        .get("https://api.swarms.world/v1/account/credits")
        .header("x-api-key", api_key)
        .header("Content-Type", "application/json")
        .send()?;

    let balance: CreditBalance = response.json()?;

    println!("✅ Credit balance retrieved successfully!");
    println!("Total Credits: ${:.2}", balance.total_credits);
    println!("Regular Credits: ${:.2}", balance.credit);
    println!("Free Credits: ${:.2}", balance.free_credit);
    println!("Referral Credits: ${:.2}", balance.referral_credits);

    Ok(())
}

package main

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
)

type CreditBalance struct {
    Credit          float64 `json:"credit"`
    FreeCredit      float64 `json:"free_credit"`
    ReferralCredits float64 `json:"referral_credits"`
    TotalCredits    float64 `json:"total_credits"`
}

func main() {
    apiKey := os.Getenv("SWARMS_API_KEY")
    if apiKey == "" {
        panic("SWARMS_API_KEY environment variable is required")
    }

    req, err := http.NewRequest("GET", "https://api.swarms.world/v1/account/credits", nil)
    if err != nil {
        panic(err)
    }

    req.Header.Set("x-api-key", apiKey)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }

    var balance CreditBalance
    if err := json.Unmarshal(body, &balance); err != nil {
        panic(err)
    }

    fmt.Println("✅ Credit balance retrieved successfully!")
    fmt.Printf("Total Credits: $%.2f\n", balance.TotalCredits)
    fmt.Printf("Regular Credits: $%.2f\n", balance.Credit)
    fmt.Printf("Free Credits: $%.2f\n", balance.FreeCredit)
    fmt.Printf("Referral Credits: $%.2f\n", balance.ReferralCredits)
}

Response Schema

CreditBalanceOutput Object

Field	Type	Description
`credit`	`number`	Regular credit balance (purchased credits)
`free_credit`	`number`	Free credit balance (promotional or welcome credits)
`referral_credits`	`number`	Credits earned through the referral program
`total_credits`	`number`	Total available credits (sum of all credit types)

Example Response

{
  "credit": 50.00,
  "free_credit": 20.00,
  "referral_credits": 5.00,
  "total_credits": 75.00
}

Credit Usage Order

Each charge is deducted from your account in this exact order (see deduct_credits in api/database_ops.py):

free_credit - Spent first
referral_credits - Spent next, once free_credit is exhausted
credit (regular/purchased) - Spent last, once both of the above are exhausted

Each bucket is tracked and returned separately in the CreditBalanceOutput response — referral_credits is not merged into credit. This ensures you maximize the value of free and referral credits before drawing down your paid balance. A request fails with 402 Payment Required if credit + free_credit + referral_credits is less than the charge.

Separately from the per-request charge check above, billable endpoints (/v1/swarm/completions, /v1/chat/completions, /v1/agent/completions, /v1/agent/batch/completions, and the other completion routes) require a total credit balance greater than $1.00 (credit + free_credit + referral_credits) before the request is even accepted — this is a pre-flight guard in the API key middleware, independent of what the specific request ends up costing.

Use Cases

Monitor Credit Balance

Check your credit balance before running large batch operations:

def check_balance_before_batch():
    balance = get_credit_balance()
    if balance and balance['total_credits'] < 10.00:
        print("⚠️ Low credit balance. Consider adding credits before running batch operations.")
        return False
    return True

if check_balance_before_batch():
    # Run batch operations
    pass

Track Credit Consumption

Monitor credit usage over time:

import time
from datetime import datetime

def track_credits(duration_minutes=60, interval_seconds=300):
    """Track credit balance over time."""
    end_time = time.time() + (duration_minutes * 60)
    
    while time.time() < end_time:
        balance = get_credit_balance()
        if balance:
            timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
            print(f"[{timestamp}] Total Credits: ${balance['total_credits']:.2f}")
        
        time.sleep(interval_seconds)

Best Practices

Regular Monitoring: Check your credit balance regularly, especially before large operations
Low Balance Alerts: Set up alerts when credits fall below a threshold
Credit Types: Understand which credit types you’re using to optimize spending
Referral Program: Earn additional credits by referring new users

Pricing Details - Understand API costs
Pricing Cost Estimator - Estimate costs before running jobs
Rate Limits - Check rate limit status
Account Management - Manage your account and add credits

Getting Started

MCP Server Tutorials

Agent Capabilities

Multi-Agent Architectures

Finance & Investing

Healthcare & Life Sciences

Legal, M&A & Diligence

Customer Operations

Defense, Gov & Supply Chain

Marketing, Content & Founder Tools

API Utilities

Migration Guides

Resources

Production

Compatibility & Benchmarks

Tutorials & Integrations

Get Credit Balance

Quick Start

Response Schema

CreditBalanceOutput Object

Example Response

Credit Usage Order

Use Cases

Monitor Credit Balance

Track Credit Consumption

Best Practices

​Quick Start

​Response Schema

​CreditBalanceOutput Object

​Example Response

​Credit Usage Order

​Use Cases

​Monitor Credit Balance

​Track Credit Consumption

​Best Practices

​Related Documentation

Quick Start

Response Schema

CreditBalanceOutput Object

Example Response

Credit Usage Order

Use Cases

Monitor Credit Balance

Track Credit Consumption

Best Practices

Related Documentation