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

There is no dedicated endpoint that returns a historical, day-by-day breakdown of your spend. The Swarms API exposes the current pricing model via /v1/usage/costs, plus a handful of related endpoints for checking your balance and activity — see Related Endpoints below.

The Usage endpoint returns the unified pricing model the API uses to calculate costs for every operation (token costs, agent costs, search/scrape costs, and the night-time discount). Use it to compute expected costs before you run a request, or to keep your own cost estimates in sync with the live pricing.

Endpoint Information

URL: /v1/usage/costs
Method: GET
Authentication: Required (x-api-key header)
Rate Limiting: Subject to tier-based rate limits

Query Parameters

None. This endpoint always returns the current pricing model in effect.

Code Examples

Python
TypeScript
cURL

import os
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",
}

response = requests.get(f"{BASE_URL}/v1/usage/costs", headers=headers)
data = response.json()

pricing = data["usage_pricing"]
print(f"Agent completions input cost: ${pricing['agent_completions_input_cost_per_1m']} / 1M tokens")
print(f"Agent completions output cost: ${pricing['agent_completions_output_cost_per_1m']} / 1M tokens")

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");
}

const res = await fetch(`${BASE_URL}/v1/usage/costs`, {
  method: "GET",
  headers: {
    "x-api-key": API_KEY,
    "Content-Type": "application/json",
  },
});

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

const data = await res.json();
console.log(data.usage_pricing);

curl -X GET "https://api.swarms.world/v1/usage/costs" \
  -H "x-api-key: $SWARMS_API_KEY"

Response Schema

PricingDetailsOutput Object

Field	Type	Description
`usage_pricing`	`object`	All per-operation costs — token costs, agent costs, search/scrape costs, night-time discount
`timestamp`	`string`	ISO timestamp when the pricing information was retrieved

usage_pricing Object

Field	Type	Description
`swarm_completions_agent_cost`	`number`	Cost per agent in swarm completions (USD)
`swarm_completions_input_cost_per_1m`	`number`	Cost per 1M input tokens for swarm completions (USD)
`swarm_completions_output_cost_per_1m`	`number`	Cost per 1M output tokens for swarm completions (USD)
`agent_completions_input_cost_per_1m`	`number`	Cost per 1M input tokens for agent completions (USD)
`agent_completions_output_cost_per_1m`	`number`	Cost per 1M output tokens for agent completions (USD)
`agent_completions_img_cost`	`number`	Cost per image for agent completions (USD)
`agent_completions_mcp_cost`	`number`	Cost per MCP call for agent completions (USD)
`search_cost`	`number`	Cost per search operation (USD)
`scrape_cost`	`number`	Cost per scrape operation (USD)
`night_time_discount`	`number`	Discount multiplier applied to swarm completion token costs, 8 PM - 6 AM PT (0.5 = 50% off)

Example Response

{
  "usage_pricing": {
    "swarm_completions_agent_cost": 0.01,
    "swarm_completions_input_cost_per_1m": 6.5,
    "swarm_completions_output_cost_per_1m": 18.5,
    "agent_completions_input_cost_per_1m": 6.5,
    "agent_completions_output_cost_per_1m": 18.5,
    "agent_completions_img_cost": 0.25,
    "agent_completions_mcp_cost": 0.1,
    "search_cost": 0.04,
    "scrape_cost": 0.15,
    "night_time_discount": 0.5
  },
  "timestamp": "2026-03-29T18:30:00+00:00"
}

Error Responses

HTTP Status	Cause
401	Missing or invalid API key
429	Rate limit exceeded
500	Internal error retrieving pricing information

For actual usage and spend tracking (rather than the pricing model itself), use:

Need	Endpoint	Returns
Current credit balance	`GET /v1/account/credits`	`credit`, `free_credit`, `referral_credits`, `total_credits`
Lifetime/recent completion counts	`GET /v1/metrics/summary`	Unique agents used, lifetime and successful completion counts, completions in the last 24h/7d
Raw request history	`GET /v1/swarm/logs`	All logged API requests for your account, which you can aggregate client-side into a custom report
Current rate limit usage	`GET /v1/rate/limits`	Requests used/remaining per minute, hour, and day

Billable completion endpoints require your total_credits balance to be above $1.00. This is checked before the request runs — if the balance is at or below the minimum, the API returns a 402 Payment Required error without doing any work. Use GET /v1/account/credits to monitor your balance.

Get Credit Balance — check your current credit balance
Pricing Details — see per-operation costs
Rate Limits — check rate limit status

Getting Started

Clients

Agent Completions

Multi-Agent

Batch

Capabilities

Resources

Swarms Cloud

Usage Report

Endpoint Information

Query Parameters

Code Examples

Response Schema

PricingDetailsOutput Object

usage_pricing Object

Example Response

Error Responses

​Endpoint Information

​Query Parameters

​Code Examples

​Response Schema

​PricingDetailsOutput Object

​usage_pricing Object

​Example Response

​Error Responses

​Related Endpoints

​Related

Endpoint Information

Query Parameters

Code Examples

Response Schema

PricingDetailsOutput Object

usage_pricing Object

Example Response

Error Responses

Related Endpoints

Related