---
title: "Get Comprehensive Pricing Details"
method: GET
path: "/v1/usage/costs"
tags: ["Pricing"]
---

# Get Comprehensive Pricing Details

`GET /v1/usage/costs`

## Request

- Base URL: `https://api.swarms.world`
- URL: `https://api.swarms.world/v1/usage/costs`
- Auth: none declared. Required headers: `x-api-key`

Retrieves comprehensive pricing details for all API features including usage costs, service costs, and special pricing features.

## Headers

- `x-api-key` string, required

## Response `200`

Successful Response

- PricingDetailsOutput: Comprehensive pricing details for all API features. Includes usage costs for all API operations and additional service costs.
  - `usage_pricing` UsagePricingModel, required: Unified pricing model for all API usage costs. Captures input and output token costs, agent costs, and additional fees for different cost structures.
    - `fallback_input_cost_per_1m` number: Cost per 1 million input tokens (USD, before the service fee) for a model with no OpenRouter or LiteLLM price, or when OpenRouter cannot be reached.
    - `fallback_output_cost_per_1m` number: Cost per 1 million output tokens (USD, before the service fee) for a model with no OpenRouter or LiteLLM price, or when OpenRouter cannot be reached.
    - `swarm_completions_agent_cost` number: Cost per agent in swarm completions (USD); agents on OpenRouter free models are not charged it.
    - `agent_completions_img_cost` number: Cost per image for agent completions (USD).
    - `search_cost` number: Cost per search operation in dollars (USD).
    - `night_time_discount` number: Discount multiplier for night time usage (0.50 = 50% discount), for paid plans only.
    - `flash_sale_active` boolean: A flag indicating whether the flash sale is active.
    - `flash_sale_discount` number: Share of the provider token price charged during a flash sale (0.50 = 50% off), with the full service fee added on top. The night time discount applies instead when it is cheaper.
  - `timestamp` string, nullable: ISO timestamp when the pricing information was retrieved.

## Other responses

- `422`: Validation Error

## Changes

- **2026-11-01** `e03f6f6e1881`: 1 breaking, 1 info
  - the response property `usage_pricing/flash_sale_active` became optional for the status `200`
  - the `flash_sale_active` response's property default value `true` was added for the status `200`
- **2026-10-31** `e330460a5543`: 2 info
  - the response property `usage_pricing/flash_sale_active` became required for the status `200`
  - the `flash_sale_active` response's property default value `true` was removed for the status `200`
- **2026-10-31** `3e13975ede3d`: 2 info
  - added the optional property `usage_pricing/flash_sale_active` to the response with the `200` status
  - added the optional property `usage_pricing/flash_sale_discount` to the response with the `200` status
- **2026-10-16** `500c79520e41`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/the-swarm-corporation/apis/swarms-api/changes/v1/usage/costs/get.md)

---

[API](https://skmtc.dev/the-swarm-corporation/apis/swarms-api.md) - [All operations](https://skmtc.dev/the-swarm-corporation/apis/swarms-api/llms.txt) - [OpenAPI document](https://skmtc.dev/the-swarm-corporation/apis/swarms-api/revisions/fca99f497199?raw)