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.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-keyheader) - 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
- Python
- TypeScript
- cURL
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
Related Endpoints
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.Related
- Get Credit Balance — check your current credit balance
- Pricing Details — see per-operation costs
- Rate Limits — check rate limit status