Skip to main content
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 flat fees the API charges (per-agent, image and search), the fallback token rates for models with no price data, the night-time discount and the flash sale settings. Tokens are billed at each model’s own price plus a 15% service fee, so per-model token prices are not in this response: get them from GET /v1/models/available or GET /v1/models/pricing?model_name=.... Use both to compute expected costs before you run a request, or to keep your own cost estimates in sync with the live pricing. See Pricing for how a charge is calculated.

Endpoint Information

  • URL: /v1/usage/costs
  • Method: GET
  • Authentication: Required (x-api-key header)
  • Rate Limiting: None. This endpoint never returns 429 and its responses carry no X-RateLimit-* headers

Query Parameters

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

Code Examples


Response Schema

PricingDetailsOutput Object

usage_pricing Object

MCP servers and the web_scraper tool have no fee of their own; only the tokens are billed. The old swarm_completions_*_cost_per_1m, agent_completions_*_cost_per_1m, agent_completions_mcp_cost and scrape_cost fields are no longer returned.

Example Response


Error Responses


Request Logs

GET /v1/account/logs returns the completions your account has run, newest first, across all of your API keys (including revoked ones). Only rows logged as completion are returned, and rows containing client IP information are left out. Each row holds the completion’s response body, not the prompt you sent. How much of that history you can read depends on your plan: Premium and Ultra both have the full history; a paid subscription with no tier set gets Pro’s limits. A free account still gets a 200 with its newest logs: truncated is true when the account has more logs than the plan shows, and upgrade_url links to the plans. Looking up one job with GET /v1/job/{job_id} works on every plan, whatever its age.
GET /v1/swarm/logs is a deprecated alias for the same endpoint, kept only for backwards compatibility. Use /v1/account/logs in new integrations.

Query parameters

SwarmLogsOutput Object


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.

MetricsSummaryOutput Object


For other account-level usage and spend tracking, use:
Billable completion endpoints require your purchased credit balance (credit, which total_credits equals) to be above $1.00. Free and referral credits don’t count and are never spent. 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, and top up at cloud.swarms.world/settings.