# Other endpoints

> List models, inspect your key, check credits and look up a generation.

Besides chat completions and [embeddings](https://clonvo.com/docs/embeddings.md), the API has a few read-only endpoints. They follow OpenRouter’s equivalents, so OpenRouter clients can read them. All of them take the same `Authorization: Bearer` header, except the model endpoints, which are public.

| Method and path | Auth | Returns |
| --- | --- | --- |
| `GET /v1/models` | None | Every available chat model, or embedding models with `output_modalities`. |
| `GET /v1/models/{author}/{slug}` | None | One model. |
| `GET /v1/embeddings/models` | None | Every available embedding model. |
| `GET /v1/key` | API key | The API key you’re calling with: limit, usage and your plan. |
| `GET /v1/credits` | API key | Your organization’s credits and usage. |
| `GET /v1/generation?id=` | API key | Metadata for one request. |

Calls with an API key count toward the key’s [request limit](https://clonvo.com/docs/rate-limits.md). Other methods on these paths return `405`.

## GET /v1/models

Lists every chat model you can call, in OpenRouter’s format. Prices are **USD per token**, as strings. No API key is needed, and responses may be cached for up to a minute.

```bash
curl https://api.clonvo.com/v1/models
```

```json
{
  "data": [
    {
      "id": "anthropic/claude-sonnet-5-5",
      "canonical_slug": "anthropic/claude-sonnet-5-5",
      "name": "Claude Sonnet 5.5",
      "created": 1790553600,
      "description": "Claude Sonnet 5.5 is Anthropic's best combination of speed and intelligence…",
      "context_length": 1000000,
      "architecture": {
        "input_modalities": ["text", "image"],
        "output_modalities": ["text"],
        "tokenizer": "Claude"
      },
      "pricing": {
        "prompt": "0.000002",
        "completion": "0.00001",
        "input_cache_read": "0.0000001",
        "input_cache_write": "0.0000025",
        "request": "0",
        "web_search": "0.01"
      },
      "top_provider": { "context_length": 1000000, "max_completion_tokens": 128000, "is_moderated": false },
      "supported_parameters": ["max_tokens", "reasoning", "tool_choice", "tools", "response_format", "structured_outputs", "include_reasoning"]
    }
  ]
}
```

| Field | Description |
| --- | --- |
| `id`, `canonical_slug` | The model id to send in `model`. |
| `created` | Release date, in Unix seconds. |
| `architecture.input_modalities` | What the model accepts: `text`, plus `image`, `file` (PDFs) and `audio` where supported. |
| `architecture.output_modalities` | `["text"]` for chat models, `["embeddings"]` for [embedding models](https://clonvo.com/docs/embeddings.md). |
| `pricing.prompt`, `pricing.completion` | USD per input and output token. |
| `pricing.input_cache_read`, `pricing.input_cache_write` | USD per token read from or written to the prompt cache. |
| `pricing.request`, `pricing.web_search` | USD per request and per web search call. `"0"` when the model has no such charge. |
| `pricing.overrides` | Only on models whose price depends on the time of day. See [Peak-hour prices](#peak-hour-prices). |
| `supported_parameters` | Request parameters the model honours, such as `tools`, `tool_choice`, `response_format`, `structured_outputs`, `reasoning`, `include_reasoning` and sampling parameters. |

Multiply a per-token price by 1,000,000 to get the per-1M price shown in the [catalogue](https://clonvo.com/models.md). Models with prompt-length tiers list their base price here; the [catalogue](https://clonvo.com/models.md) shows every price. Free models (`:free`) are included with zero prices, as OpenRouter lists them. Retired models and models that are temporarily switched off aren’t listed.

As on OpenRouter, the list holds chat models unless you ask for others with `output_modalities`: a comma-separated list of `text` (the default) and `embeddings`, or `all`.

```bash
curl "https://api.clonvo.com/v1/models?output_modalities=embeddings"
```

Embedding models have a `pricing.prompt` per input token, a `pricing.completion` of `"0"`, a `context_length` that is the most tokens one input may have, and `supported_parameters` of `encoding_format`, plus `dimensions` where the model can shorten its vectors.

### Peak-hour prices

A few models cost more at busy times of day. For these, the top-level `pricing` is the off-peak price, and `pricing.overrides` lists the week's windows in the same format OpenRouter uses. Each entry applies while all of its conditions match, and any price an entry leaves out stays at the top-level value. `utc_start` and `utc_end` are UTC times written as HHMM (`100` is 01:00), and a window whose end isn't after its start runs past midnight (`utc_end: 0` means until midnight). `utc_days` names the UTC weekdays the window covers. The windows cover the whole week, so exactly one applies at any moment. For example, DeepSeek V4.1 Flash costs twice as much from 01:00 to 04:00 and from 06:00 to 10:00 UTC on weekdays:

```json
"pricing": {
  "prompt": "0.00000015",
  "completion": "0.0000006",
  "input_cache_read": "0.000000003",
  "input_cache_write": "0",
  "request": "0",
  "web_search": "0",
  "overrides": [
    { "utc_days": ["sunday", "saturday"], "prompt": "0.00000015", "completion": "0.0000006", "input_cache_read": "0.000000003" },
    { "utc_start": 0, "utc_end": 100, "utc_days": ["monday", "tuesday", "wednesday", "thursday", "friday"], "prompt": "0.00000015", "completion": "0.0000006", "input_cache_read": "0.000000003" },
    { "utc_start": 100, "utc_end": 400, "utc_days": ["monday", "tuesday", "wednesday", "thursday", "friday"], "prompt": "0.0000003", "completion": "0.0000012", "input_cache_read": "0.000000006" },
    { "utc_start": 400, "utc_end": 600, "utc_days": ["monday", "tuesday", "wednesday", "thursday", "friday"], "prompt": "0.00000015", "completion": "0.0000006", "input_cache_read": "0.000000003" },
    { "utc_start": 600, "utc_end": 1000, "utc_days": ["monday", "tuesday", "wednesday", "thursday", "friday"], "prompt": "0.0000003", "completion": "0.0000012", "input_cache_read": "0.000000006" },
    { "utc_start": 1000, "utc_end": 0, "utc_days": ["monday", "tuesday", "wednesday", "thursday", "friday"], "prompt": "0.00000015", "completion": "0.0000006", "input_cache_read": "0.000000003" }
  ]
}
```

A request is charged the price in effect when it reaches Clonvo, and `usage.cost` in the response reports that price.

## GET /v1/embeddings/models

The embedding models alone, in the same format: the same list as `GET /v1/models?output_modalities=embeddings`.

## GET /v1/models/{author}/{slug}

Returns `{"data": {…}}` with one model object in the same format, for example `GET /v1/models/x-ai/grok-4-7`. Embedding models are found here too. Unknown or unavailable models return `404` with the code `model_not_found`.

## GET /v1/key

Describes the API key in the `Authorization` header.

```bash
curl https://api.clonvo.com/v1/key -H "Authorization: Bearer $CLONVO_API_KEY"
```

```json
{
  "data": {
    "label": "Production backend",
    "usage": 118.4,
    "usage_period": 18.75,
    "limit": 50,
    "limit_remaining": 31.25,
    "limit_reset": "monthly",
    "limit_resets_at": "2026-11-01T00:00:00.000Z",
    "plan": "standard",
    "is_free_tier": false,
    "is_provisioning_key": false,
    "expires_at": null,
    "project_id": "prj_01M5ZQ2W8X3N4P6R7S9T1V2Y3Z"
  }
}
```

| Field | Description |
| --- | --- |
| `label` | The key’s name. |
| `usage` | Lifetime amount charged on this key in USD: credits spent, plus any fees on your own provider keys. |
| `usage_period` | Amount charged in the current limit period. Equals `usage` when the key has no reset. |
| `limit` | Spending limit in USD, or `null` for no limit. |
| `limit_remaining` | What’s left in the current period, or `null` when there’s no limit. |
| `limit_reset` | `daily`, `weekly`, `monthly`, or `null` for a lifetime limit. |
| `limit_resets_at` | When the current period ends (UTC), or `null`. |
| `plan` | Your organization’s [plan](https://clonvo.com/docs/plans.md): `free` (Free), `standard` (Pay as you go) or `enterprise` (Enterprise). |
| `is_free_tier` | `true` while your organization is on Free, the same as `plan` being `free`. |
| `is_provisioning_key` | Always `false`. Clonvo doesn’t have provisioning keys. |
| `expires_at` | The key’s expiry time, or `null`. |
| `project_id` | The project the key belongs to. |

## GET /v1/credits

Returns your organization’s credits and usage, in USD. The balance is `total_credits − total_usage`.

```json
{
  "data": {
    "total_credits": 110,
    "total_usage": 42.17
  }
}
```

`total_usage` is everything deducted from credits: requests on credits and fees on your own provider keys. `total_credits` is your current balance plus `total_usage`, so it includes purchases and any credit adjustments made to your balance.

## GET /v1/generation

Looks up one request by the `id` returned in its response (`gen-…`) or in the `x-clonvo-generation-id` header.

```bash
curl "https://api.clonvo.com/v1/generation?id=gen-01M67FGKKVQ8ZK2M3N5P7R9S1V" \
  -H "Authorization: Bearer $CLONVO_API_KEY"
```

```json
{
  "data": {
    "id": "gen-01M67FGKKVQ8ZK2M3N5P7R9S1V",
    "kind": "chat",
    "created_at": "2026-10-30T22:40:00.123Z",
    "model": "anthropic/claude-sonnet-5-5",
    "requested_model": "anthropic/claude-sonnet-5.5",
    "provider_name": "Anthropic",
    "upstream_id": "msg_01XFDUDYJgAACzvnptvVoYEL",
    "origin": "https://example.com",
    "app_title": "Example App",
    "source": "api",
    "status": "success",
    "streamed": true,
    "cancelled": false,
    "finish_reason": "stop",
    "http_status": 200,
    "error": null,
    "is_byok": false,
    "billing_mode": "credits",
    "total_cost": 0.0035544,
    "usage": 0.0035544,
    "latency": 3180,
    "time_to_first_token": 412,
    "tokens_prompt": 1200,
    "tokens_completion": 310,
    "native_tokens_prompt": 1200,
    "native_tokens_completion": 310,
    "native_tokens_reasoning": 0,
    "native_tokens_cached": 1024,
    "native_tokens_cache_write": 0,
    "num_tool_calls": 0,
    "attempts": 1,
    "has_content": false,
    "project_id": "prj_01M5ZQ2W8X3N4P6R7S9T1V2Y3Z",
    "api_key_id": "key_01M5ZQ4B6C8D9E1F2G3H4J5K6M"
  }
}
```

| Field | Description |
| --- | --- |
| `kind` | `chat` for model requests, `embedding` for [embeddings](https://clonvo.com/docs/embeddings.md) (input tokens only, so `tokens_completion` is `0`), `tool` for [tool calls](https://clonvo.com/docs/tools.md). For a tool call, `model` is the tool id (such as `web_search`), `provider_name` is the tool provider and the token fields are `0`. |
| `model` | The model that served the request. `requested_model` is what you sent in `model`. |
| `provider_name` | The provider that served it. |
| `origin`, `app_title` | Your `HTTP-Referer` and `X-Title` headers, if you sent them. |
| `source` | `api`, or `playground` for requests from the dashboard playground. |
| `status` | `success`, `error` or `cancelled`. `error` has `code` and `message` when the request failed. |
| `billing_mode` | `credits`, `byok` or `free`. `null` when no attempt reached a provider. |
| `total_cost` | What the request cost at list price, in USD (the same as `usage.cost` in the response). |
| `usage` | What was actually deducted from your credits, in USD. For requests on your own keys this is Clonvo’s fee, usually `0`. |
| `latency` | Total time in milliseconds. |
| `time_to_first_token` | Milliseconds until the first streamed chunk, or `null`. |
| `tokens_prompt`, `tokens_completion` | Input and output tokens. Cached and cache-write tokens are included in `tokens_prompt`; reasoning tokens in `tokens_completion`. |
| `attempts` | How many provider attempts were made, including [fallbacks](https://clonvo.com/docs/fallbacks.md). |
| `has_content` | Whether the prompt and response were stored (see [Data and privacy](https://clonvo.com/docs/privacy.md)). |

Usage is recorded a few seconds after a request finishes, so a lookup straight after the response may return `404` with the code `generation_not_found`. Retry after a short delay. You can only look up requests from your own organization.