> ## 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.

# Premium Endpoints API

> Fetch the current list of premium-only API endpoints programmatically, with route, feature name, and description for each

Retrieve every endpoint that requires a premium subscription from `/v1/account/premium-endpoints`. Each entry carries the route, a human-readable feature name, and a description of what the endpoint unlocks — so your application can gate its own UI without hardcoding a list that drifts out of date.

<Info>
  This endpoint returns the *catalog* of premium routes. It does not tell you whether **your** account has premium access — a free-tier key can call it successfully and still receive `403` when it tries one of the listed routes. See [Premium Endpoints](/docs/documentation/resources/premium-endpoints) for the tier rules.
</Info>

## Endpoint

| Property | Value |
| - | - |
| **Method** | `GET` |
| **Path** | `/v1/account/premium-endpoints` |
| **Base URL** | `https://api.swarms.world` |
| **Authentication** | `x-api-key` header (required) |
| **Tier** | Available on all tiers |

## Quick Start

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    import os
    import json
    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_premium_endpoints() -> dict | None:
        """Fetch the catalog of premium-only endpoints."""
        resp = requests.get(
            f"{BASE_URL}/v1/account/premium-endpoints",
            headers=headers,
        )

        if resp.status_code == 200:
            return resp.json()

        print(f"Error: {resp.status_code} - {resp.text}")
        return None

    if __name__ == "__main__":
        data = get_premium_endpoints()
        if data:
            print(f"✅ {data['total']} premium endpoints")
            for endpoint in data["premium_endpoints"]:
                print(f"  {endpoint['route']:45} {endpoint['name']}")
            print(f"\nUpgrade at: {data['upgrade_url']}")
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const API_KEY = process.env.SWARMS_API_KEY;
    const BASE_URL = "https://api.swarms.world";

    const headers = {
        "x-api-key": API_KEY,
        "Content-Type": "application/json"
    };

    async function getPremiumEndpoints() {
        const response = await fetch(`${BASE_URL}/v1/account/premium-endpoints`, {
            method: 'GET',
            headers: headers
        });

        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }

        const data = await response.json();
        console.log(`✅ ${data.total} premium endpoints`);
        data.premium_endpoints.forEach(e => {
            console.log(`  ${e.route.padEnd(45)} ${e.name}`);
        });
        console.log(`\nUpgrade at: ${data.upgrade_url}`);
        return data;
    }

    getPremiumEndpoints();
    ```
  </Tab>

  <Tab title="Shell (curl)">
    ```bash theme={null}
    curl -sS -X GET "https://api.swarms.world/v1/account/premium-endpoints" \
      -H "x-api-key: $SWARMS_API_KEY"
    ```

    Extract just the routes:

    ```bash theme={null}
    curl -sS "https://api.swarms.world/v1/account/premium-endpoints" \
      -H "x-api-key: $SWARMS_API_KEY" \
      | jq -r '.premium_endpoints[].route'
    ```
  </Tab>
</Tabs>

## Response

```json theme={null}
{
  "status": true,
  "timestamp": "2026-08-24T18:00:00.000000+00:00",
  "total": 5,
  "premium_endpoints": [
    {
      "route": "/v1/agent/batch/completions",
      "name": "Batch Agent Completions",
      "description": "process multiple agent tasks concurrently in a single request"
    },
    {
      "route": "/v1/swarm/batch/completions",
      "name": "Batch Swarm Completions",
      "description": "execute multiple swarm workflows in parallel"
    },
    {
      "route": "/v1/reasoning-agent/completions",
      "name": "Reasoning Agent Completions",
      "description": "leverage advanced reasoning capabilities with enhanced agent intelligence"
    },
    {
      "route": "/v1/batched-grid-workflow/completions",
      "name": "Batched Grid Workflows",
      "description": "execute grid-based workflows with multiple agents and tasks in parallel"
    },
    {
      "route": "/v1/graph-workflow/completions",
      "name": "Graph Workflows",
      "description": "orchestrate complex multi-agent workflows with directed graphs and parallel execution"
    }
  ],
  "upgrade_url": "https://cloud.swarms.world/settings"
}
```

<Note>
  The `name` and `description` strings above are the literal values the API returns (lowercase, verb-first descriptions) — copy them as-is rather than re-casing them, since your gating logic may match on exact string.
</Note>

### Response Schema

| Field | Type | Description |
| - | - | - |
| `status` | `boolean` | Whether fetching the premium endpoints succeeded. Defaults to `true`. |
| `timestamp` | `string \| null` | ISO-formatted timestamp of when the response was generated. |
| `total` | `integer` | Number of premium endpoints. |
| `premium_endpoints` | `array` | One `PremiumEndpointInfo` object per premium-only route. |
| `upgrade_url` | `string` | Where to upgrade to a premium subscription. |

### PremiumEndpointInfo

| Field | Type | Description |
| - | - | - |
| `route` | `string` | The API route path that requires a premium subscription. |
| `name` | `string` | Human-readable feature name for the endpoint. |
| `description` | `string` | What the endpoint allows a premium subscriber to do. |

### Status Codes

| Code | Meaning |
| - | - |
| `200` | Catalog returned successfully |
| `401` | Missing or invalid `x-api-key` |
| `422` | Validation error — the `x-api-key` header was not supplied |

## Gating Your Own UI

Rather than shipping a hardcoded list, fetch the catalog at startup and use it to decide what to show:

```python theme={null}
PREMIUM_ROUTES = {
    e["route"] for e in get_premium_endpoints()["premium_endpoints"]
}

def is_premium(route: str) -> bool:
    """True when a route needs a premium subscription."""
    return route in PREMIUM_ROUTES

# Disable the batch button for free-tier users instead of letting the call 403
if is_premium("/v1/swarm/batch/completions"):
    show_upgrade_prompt()
```

<Warning>
  The catalog changes as endpoints are added or re-tiered. Cache it for minutes, not for the lifetime of a deployment, and never bake the routes into a released binary.
</Warning>

## Related Resources

<CardGroup cols={2}>
  <Card title="Premium Endpoints" icon="star" href="/docs/documentation/resources/premium-endpoints">
    Tier rules and the 403 error shape
  </Card>

  <Card title="Pricing" icon="tag" href="/docs/documentation/resources/pricing">
    Plan comparison and model gating
  </Card>

  <Card title="Credit Balance" icon="wallet" href="/docs/examples/examples/account-credits">
    Premium endpoints also require credits above \$1.00
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/docs/examples/api_examples/rate_limits">
    Tier-based request limits
  </Card>
</CardGroup>


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