> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swarms.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage Report

> API reference for reporting on your Swarms API usage: current pricing (GET /v1/usage/costs), request logs (GET /v1/account/logs), and a metrics summary (GET /v1/account/metrics/summary).

<Info>
  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.
</Info>

The Usage endpoint returns the unified pricing model the API uses to calculate costs for every operation (token costs, agent costs, search/scrape costs, and the night-time discount). Use it to compute expected costs before you run a request, or to keep your own cost estimates in sync with the live pricing.

## Endpoint Information

* **URL**: `/v1/usage/costs`
* **Method**: `GET`
* **Authentication**: Required (`x-api-key` header)
* **Rate Limiting**: Subject to tier-based rate limits

***

## Query Parameters

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

***

## Code Examples

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    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",
    }

    response = requests.get(f"{BASE_URL}/v1/usage/costs", headers=headers)
    data = response.json()

    pricing = data["usage_pricing"]
    print(f"Agent completions input cost: ${pricing['agent_completions_input_cost_per_1m']} / 1M tokens")
    print(f"Agent completions output cost: ${pricing['agent_completions_output_cost_per_1m']} / 1M tokens")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import "dotenv/config";

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

    if (!API_KEY) {
      throw new Error("SWARMS_API_KEY is not set");
    }

    const res = await fetch(`${BASE_URL}/v1/usage/costs`, {
      method: "GET",
      headers: {
        "x-api-key": API_KEY,
        "Content-Type": "application/json",
      },
    });

    if (!res.ok) {
      throw new Error(`HTTP ${res.status}: ${await res.text()}`);
    }

    const data = await res.json();
    console.log(data.usage_pricing);
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X GET "https://api.swarms.world/v1/usage/costs" \
      -H "x-api-key: $SWARMS_API_KEY"
    ```
  </Tab>
</Tabs>

***

## Response Schema

### PricingDetailsOutput Object

| Field | Type | Description |
| - | - | - |
| `usage_pricing` | `object` | All per-operation costs — token costs, agent costs, search/scrape costs, night-time discount |
| `timestamp` | `string` | ISO timestamp when the pricing information was retrieved |

### usage\_pricing Object

| Field | Type | Description |
| - | - | - |
| `swarm_completions_agent_cost` | `number` | Cost per agent in swarm completions (USD) |
| `swarm_completions_input_cost_per_1m` | `number` | Cost per 1M input tokens for swarm completions (USD) |
| `swarm_completions_output_cost_per_1m` | `number` | Cost per 1M output tokens for swarm completions (USD) |
| `agent_completions_input_cost_per_1m` | `number` | Cost per 1M input tokens for agent completions (USD) |
| `agent_completions_output_cost_per_1m` | `number` | Cost per 1M output tokens for agent completions (USD) |
| `agent_completions_img_cost` | `number` | Cost per image for agent completions (USD) |
| `agent_completions_mcp_cost` | `number` | Cost per MCP call for agent completions (USD) |
| `search_cost` | `number` | Cost per search operation (USD) |
| `scrape_cost` | `number` | Cost per scrape operation (USD) |
| `night_time_discount` | `number` | Discount multiplier applied to swarm completion token costs, 8 PM - 6 AM PT (0.5 = 50% off) |

### Example Response

```json theme={null}
{
  "usage_pricing": {
    "swarm_completions_agent_cost": 0.01,
    "swarm_completions_input_cost_per_1m": 6.5,
    "swarm_completions_output_cost_per_1m": 18.5,
    "agent_completions_input_cost_per_1m": 6.5,
    "agent_completions_output_cost_per_1m": 18.5,
    "agent_completions_img_cost": 0.25,
    "agent_completions_mcp_cost": 0.1,
    "search_cost": 0.04,
    "scrape_cost": 0.15,
    "night_time_discount": 0.5
  },
  "timestamp": "2026-03-29T18:30:00+00:00"
}
```

***

## Error Responses

| HTTP Status | Cause |
| - | - |
| 401 | Missing or invalid API key |
| 429 | Rate limit exceeded |
| 500 | Internal error retrieving pricing information |

***

## Request Logs

`GET /v1/account/logs` returns your account's full API request history — every logged request across all of your API keys (including revoked ones), excluding client IP information.

<Note>
  `GET /v1/swarm/logs` is a **deprecated alias** for the same endpoint, kept only for backwards compatibility. Use `/v1/account/logs` in new integrations.
</Note>

```bash theme={null}
curl -H "x-api-key: $SWARMS_API_KEY" \
     https://api.swarms.world/v1/account/logs
```

### SwarmLogsOutput Object

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Status of the request |
| `count` | `integer` | Exact total number of matching log entries across every API key on the account, including revoked ones. This is **not** `len(logs)` — `logs` is capped at the 1000 newest entries, so `count` exceeds it once your account passes 1000 requests |
| `logs` | `array` | Log entries with timestamps, endpoints, and status (capped at the 1000 newest) |
| `timestamp` | `string` | ISO timestamp when the response was generated |

```json theme={null}
{
  "status": "success",
  "count": 1284,
  "logs": [
    {
      "endpoint": "/v1/agent/completions",
      "status": "success",
      "timestamp": "2026-09-14T09:12:03+00:00"
    }
  ],
  "timestamp": "2026-09-14T12:00:00+00:00"
}
```

***

## Metrics Summary

`GET /v1/account/metrics/summary` returns an at-a-glance overview of your core usage metrics across all of your API keys.

<Note>
  `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.
</Note>

```bash theme={null}
curl -H "x-api-key: $SWARMS_API_KEY" \
     https://api.swarms.world/v1/account/metrics/summary
```

### MetricsSummaryOutput Object

| Field | Type | Description |
| - | - | - |
| `success` | `boolean` | Whether the summary was retrieved successfully |
| `unique_agents` | `integer` | Number of unique agent configurations you've 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 timestamp when the summary was generated |

```json theme={null}
{
  "success": true,
  "unique_agents": 14,
  "total_completion_calls": 1284,
  "successful_completions": 1259,
  "completions_last_24h": 37,
  "completions_last_7d": 214,
  "timestamp": "2026-09-14T12:00:00+00:00"
}
```

***

## Related Endpoints

For other account-level usage and spend tracking, use:

| Need | Endpoint | Returns |
| - | - | - |
| Current credit balance | `GET /v1/account/credits` | `credit`, `free_credit`, `referral_credits`, `total_credits` |
| Current rate limit usage | `GET /v1/rate/limits` | Requests used/remaining per minute, hour, and day |

<Note>
  Billable completion endpoints require your `total_credits` balance to be above \$1.00. 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.
</Note>

***

## Related

* [Get Credit Balance](/docs/examples/examples/account-credits) — check your current credit balance
* [Pricing Details](/docs/examples/examples/pricing-details-basic) — see per-operation costs
* [Rate Limits](/docs/examples/api_examples/rate_limits) — check rate limit status


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.