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

The Metrics Summary endpoint (/v1/metrics/summary) returns an at-a-glance overview of your account’s core usage metrics — how many unique agents you’ve used and completion-call counts derived from your request history — in a single response. This is the endpoint to power a usage dashboard: unique agents used, lifetime completion calls, and recent-window activity.

Endpoint Information

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

Response Format

The endpoint returns a JSON object with the following fields:

Field	Type	Description
`success`	boolean	Indicates the summary was retrieved successfully.
`unique_agents`	integer	Number of unique agent configurations you have 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 8601 UTC timestamp when the summary was generated.

Example Response

{
  "success": true,
  "unique_agents": 80,
  "total_completion_calls": 25583,
  "successful_completions": 13516,
  "completions_last_24h": 2,
  "completions_last_7d": 1151,
  "timestamp": "2026-07-06T11:54:17.401905+00:00"
}

Use Cases

Usage dashboards: Populate headline tiles (executions, success rate, unique agents) from a single request.
Activity monitoring: Track 24-hour and 7-day completion volume to spot spikes or drop-offs.

Python
JavaScript
cURL

import json
import os
from typing import Any, Dict

import requests
from dotenv import load_dotenv

load_dotenv()

BASE_URL = "https://api.swarms.world"

HEADERS = {
    "x-api-key": os.getenv("SWARMS_API_KEY"),
    "Content-Type": "application/json",
}

def get_metrics_summary() -> Dict[str, Any]:
    """Retrieve a summary of your core usage metrics"""
    try:
        response = requests.get(
            f"{BASE_URL}/v1/metrics/summary",
            headers=HEADERS,
        )
        assert response.status_code == 200, f"Expected 200, got {response.status_code}: {response.text}"
        data = response.json()

        print(json.dumps(data, indent=4))
        print(f"Unique agents:           {data['unique_agents']}")
        print(f"Total completion calls:  {data['total_completion_calls']}")
        print(f"Successful completions:  {data['successful_completions']}")
        print(f"Last 24h / 7d:           {data['completions_last_24h']} / {data['completions_last_7d']}")
        return data
    except Exception as e:
        print(str(e))
        return {}

if __name__ == "__main__":
    get_metrics_summary()

require('dotenv').config();

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

async function getMetricsSummary() {
  const url = `${BASE_URL}/v1/metrics/summary`;
  const resp = await fetch(url, {
    method: 'GET',
    headers: {
      'x-api-key': API_KEY,
      'Content-Type': 'application/json',
    },
  });
  if (!resp.ok) {
    console.error(`Error: ${resp.status} - ${await resp.text()}`);
    return;
  }
  const data = await resp.json();
  console.log(JSON.stringify(data, null, 2));
  console.log(`Unique agents:          ${data.unique_agents}`);
  console.log(`Total completion calls: ${data.total_completion_calls}`);
  console.log(`Successful completions: ${data.successful_completions}`);
  console.log(`Last 24h / 7d:          ${data.completions_last_24h} / ${data.completions_last_7d}`);
}

getMetricsSummary().catch(console.error);

#!/usr/bin/env bash

BASE_URL="https://api.swarms.world"

curl -X GET "${BASE_URL}/v1/metrics/summary" \
  -H "x-api-key: ${SWARMS_API_KEY}" \
  -H "Content-Type: application/json"

To list your agent configurations, use /v1/agents/list; for full request logs, use /v1/swarm/logs.

Getting Started

Clients

Agent Completions

Multi-Agent

Batch

Capabilities

Resources

Swarms Cloud

User Metrics Summary

Endpoint Information

Response Format

Example Response

Use Cases

​Endpoint Information

​Response Format

​Example Response

​Use Cases

Endpoint Information

Response Format

Example Response

Use Cases