Skip to main content
Leverage the /v1/usage/costs endpoint to estimate end-to-end workload costs before running large jobs. This example shows how to turn the unified pricing model into a simple cost calculator.
All cost values are returned in USD. Always re-fetch pricing in long‑lived services to reflect updates in real time.

Example: Cost Estimation Workflow

The following examples:
  • Fetch pricing details from /v1/usage/costs
  • Estimate costs for:
    • Swarm completions (input/output tokens + per‑agent fee)
    • Agent completions (input/output tokens)
    • Images, MCP calls, search, and scrape operations
    • Optional night-time discount multiplier
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",
}

def get_pricing():
    resp = requests.get(f"{BASE_URL}/v1/usage/costs", headers=headers)
    resp.raise_for_status()
    return resp.json()["usage_pricing"]

def estimate_cost(usage_pricing: dict, *, swarm_input_tokens: int = 0,
                  swarm_output_tokens: int = 0, swarm_agents: int = 0,
                  agent_input_tokens: int = 0, agent_output_tokens: int = 0,
                  images: int = 0, mcp_calls: int = 0,
                  searches: int = 0, scrapes: int = 0,
                  night_time: bool = False) -> float:
    up = usage_pricing

    def tokens_to_m(tokens: int) -> float:
        return tokens / 1_000_000.0

    cost = 0.0

    # Swarm completions
    cost += tokens_to_m(swarm_input_tokens) * up["swarm_completions_input_cost_per_1m"]
    cost += tokens_to_m(swarm_output_tokens) * up["swarm_completions_output_cost_per_1m"]
    cost += swarm_agents * up["swarm_completions_agent_cost"]

    # Agent completions
    cost += tokens_to_m(agent_input_tokens) * up["agent_completions_input_cost_per_1m"]
    cost += tokens_to_m(agent_output_tokens) * up["agent_completions_output_cost_per_1m"]

    # Images, MCP, search, scrape
    cost += images * up["agent_completions_img_cost"]
    cost += mcp_calls * up["agent_completions_mcp_cost"]
    cost += searches * up["search_cost"]
    cost += scrapes * up["scrape_cost"]

    if night_time:
        cost *= up["night_time_discount"]

    return round(cost, 6)

if __name__ == "__main__":
    pricing = get_pricing()

    est = estimate_cost(
        pricing,
        swarm_input_tokens=800_000,
        swarm_output_tokens=400_000,
        swarm_agents=3,
        agent_input_tokens=500_000,
        agent_output_tokens=250_000,
        images=4,
        mcp_calls=10,
        searches=20,
        scrapes=5,
        night_time=True,
    )

    print(f"💰 Estimated workload cost: ${est}")

When to Use This Pattern

  • Pre-flight cost estimation before running large batch jobs or swarms
  • Dashboards and billing UIs that surface live pricing alongside your own usage metrics
  • Guardrails that block workloads projected to exceed a configured budget