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. Instead, the Swarms API exposes three complementary pieces: the current pricing model (/v1/usage/costs), your raw request logs (/v1/account/logs), and an at-a-glance metrics summary (/v1/account/metrics/summary). Combine these client-side for a custom usage report — see each section 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

Request Logs

GET /v1/account/logs returns your account’s full API request history — every logged request across all of your API keys (including revoked ones), excluding client IP information.

GET /v1/swarm/logs is a deprecated alias for the same endpoint, kept only for backwards compatibility. Use /v1/account/logs in new integrations.

curl -H "x-api-key: $SWARMS_API_KEY" \
     https://api.swarms.world/v1/account/logs

SwarmLogsOutput Object

Field	Type	Description
`status`	`string`	Status of the request
`count`	`integer`	Exact total number of matching log entries across every API key on the account, including revoked ones. This is not `len(logs)` — `logs` is capped at the 1000 newest entries, so `count` exceeds it once your account passes 1000 requests
`logs`	`array`	Log entries with timestamps, endpoints, and status (capped at the 1000 newest)
`timestamp`	`string`	ISO timestamp when the response was generated

{
  "status": "success",
  "count": 1284,
  "logs": [
    {
      "endpoint": "/v1/agent/completions",
      "status": "success",
      "timestamp": "2026-09-14T09:12:03+00:00"
    }
  ],
  "timestamp": "2026-09-14T12:00:00+00:00"
}

Metrics Summary

GET /v1/account/metrics/summary returns an at-a-glance overview of your core usage metrics across all of your API keys.

GET /v1/metrics/summary is a deprecated alias for the same endpoint, kept only for backwards compatibility. Use /v1/account/metrics/summary in new integrations.

curl -H "x-api-key: $SWARMS_API_KEY" \
     https://api.swarms.world/v1/account/metrics/summary

MetricsSummaryOutput Object

Field	Type	Description
`success`	`boolean`	Whether the summary was retrieved successfully
`unique_agents`	`integer`	Number of unique agent configurations you’ve used
`total_completion_calls`	`integer`	Lifetime count of completion calls
`successful_completions`	`integer`	Lifetime count of completions with status `success`
`completions_last_24h`	`integer`	Completion calls in the last 24 hours
`completions_last_7d`	`integer`	Completion calls in the last 7 days
`timestamp`	`string`	ISO timestamp when the summary was generated

{
  "success": true,
  "unique_agents": 14,
  "total_completion_calls": 1284,
  "successful_completions": 1259,
  "completions_last_24h": 37,
  "completions_last_7d": 214,
  "timestamp": "2026-09-14T12:00:00+00:00"
}

For other account-level usage and spend tracking, use:

Need	Endpoint	Returns
Current credit balance	`GET /v1/account/credits`	`credit`, `free_credit`, `referral_credits`, `total_credits`
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

Request Logs

SwarmLogsOutput Object

Metrics Summary

MetricsSummaryOutput Object

​Endpoint Information

​Query Parameters

​Code Examples

​Response Schema

​PricingDetailsOutput Object

​usage_pricing Object

​Example Response

​Error Responses

​Request Logs

​SwarmLogsOutput Object

​Metrics Summary

​MetricsSummaryOutput Object

​Related Endpoints

​Related

Endpoint Information

Query Parameters

Code Examples

Response Schema

PricingDetailsOutput Object

usage_pricing Object

Example Response

Error Responses

Request Logs

SwarmLogsOutput Object

Metrics Summary

MetricsSummaryOutput Object

Related Endpoints

Related