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

# API documentation

> Get checked model demand and public model facts with anonymous, read-only GET requests.

**API version:** `model-demand.agent-api.v1` · **Response:** JSON · **Authentication:** No API key required.

<span id="overview" />

## What this API contains

The [models endpoint](/api-reference/models) returns ranked OpenRouter demand and checked model facts, availability states, source details, and pagination. The [about endpoint](/api-reference/about) defines the current agent contract.

The separate [`/api/supply` feed](/api-reference/data-feeds) contains provider supply and supply history. This feed is outside the formal v1 agent schema. It is not part of the `/api/v1/models` response. This API does not identify underserved models. Demand or missing data does not prove a supply opportunity.

The documentation is hosted at `docs.inferenceproviderstats.com`. API requests go to `https://www.inferenceproviderstats.com`; existing API URLs continue to work.

## Quick start

1. Read the about route for definitions and limits.
2. List models with an explicit sort and limit.
3. Use an exact, URL-encoded model ID when you need one model.
4. Report the generation time, freshness, and source limits.

<CodeGroup>
  ```bash Read the contract theme={null}
  curl "https://www.inferenceproviderstats.com/api/v1/about"
  ```

  ```bash List models theme={null}
  curl "https://www.inferenceproviderstats.com/api/v1/models?sort=tokens_30d&order=desc&limit=10"
  ```

  ```bash Exact model theme={null}
  curl "https://www.inferenceproviderstats.com/api/v1/models?model_id=qwen%2Fqwen3-8b"
  ```

  ```bash Model with a variant theme={null}
  curl "https://www.inferenceproviderstats.com/api/v1/models?model_id=openai%2Fgpt-oss-120b%3Afree"
  ```
</CodeGroup>

### Example response shape

Decimal quantities use strings so clients can preserve exact values. This illustrative sample contains no model records and is not current production data.

```json theme={null}
{
  "schema_version": "model-demand.agent-api.v1",
  "generated_at": "2026-08-25T12:00:00Z",
  "evaluation_cutoff": "2026-08-24T23:59:59Z",
  "freshness": {
    "state": "fresh",
    "fresh_until": "2026-08-26T13:01:00Z",
    "reason": "within_expected_update_window"
  },
  "window": {
    "start_date": "2026-07-26",
    "end_date": "2026-08-24",
    "days": 30
  },
  "source": {
    "name": "OpenRouter",
    "url": "https://openrouter.ai/rankings",
    "terms_url": "https://openrouter.ai/docs/cookbook/administration/data-api",
    "checked_at": "2026-08-25T11:00:00Z",
    "license": "CC BY 4.0",
    "attribution": "Source: OpenRouter (openrouter.ai/rankings), as of 2026-08-24. Licensed under CC BY 4.0."
  },
  "query": {
    "mode": "list",
    "model_id": null,
    "sort": "tokens_30d",
    "order": "desc",
    "limit": 10,
    "offset": 0
  },
  "pagination": {
    "total_matching_models": 0,
    "offset": 0,
    "limit": 10,
    "returned_count": 0,
    "has_next_page": false
  },
  "models": []
}
```

## Query reference

All parameters are optional. `model_id` selects an exact lookup. Do not combine it with `sort`, `order`, `limit`, or `offset`. Unknown or repeated parameters return an invalid-query response.

| Parameter  | Type    | Default     | Allowed values                                                                                                                         | Limit                 |
| ---------- | ------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| `model_id` | string  | none        | Any exact model ID                                                                                                                     | Exact lookup only     |
| `sort`     | string  | tokens\_30d | tokens\_30d, latest\_rank, total\_parameters, active\_parameters, smallest\_quant\_checkpoint\_bytes, full\_sequence\_attention\_bytes | List mode             |
| `order`    | string  | desc        | asc, desc                                                                                                                              | List mode             |
| `limit`    | integer | 25          | Integer                                                                                                                                | 1 to 100              |
| `offset`   | integer | 0           | Integer                                                                                                                                | 0 to 9007199254740991 |

Follow `pagination.has_next_page` and advance `offset` by the page limit. Unavailable sort values appear after available values; model ID breaks ties.

<span id="field-reference" />

## Field and unit glossary

The [complete field reference](/api-reference/fields) is generated from the same definitions as `/api/v1/about`. Units are exact contract values. A `fraction` is a share from 0 to 1, not a percentage. Byte values are not GiB values.

<span id="interpretation" />

## Freshness and source limits

`generated_at` is the time when the accepted export was generated. `evaluation_cutoff` is the latest evidence time in that export. `fresh_until` is the freshness deadline. Check `freshness.state` and its reason before reporting results.

Demand data contains the OpenRouter top 50 models. Models outside the cutoff do not have separate rows. Missing detail is unknown, not zero.

Keep each value, state, and reason together. Do not replace a null value with a number. Use [`/api/export`](/api-reference/data-feeds) for daily demand history; the models route returns checked aggregates.

Read the [methods and evidence limits](/methods) before comparing models or interpreting supply.

## Errors

| HTTP status | Error              | Meaning                                                            |
| ----------- | ------------------ | ------------------------------------------------------------------ |
| `400`       | `invalid_query`    | Unknown, repeated, out-of-range, or incompatible query parameters. |
| `404`       | `model_not_found`  | The exact model ID is absent from the accepted public export.      |
| `503`       | `data_unavailable` | The service cannot provide accepted public data.                   |

Error responses use `schema_version: "model-demand.agent-api-error.v1"`, `error`, and `message`. A successful empty list is a `200` response, not an error. See the [OpenAPI document](https://www.inferenceproviderstats.com/api/openapi.json) for the complete schema.

## Agent prompts

Copy this prompt into Codex or Claude, then append your question.

```text theme={null}
Use the public Model Demand Analytics site and API to answer my question about OpenRouter model demand, model size, model facts, or provider supply.

Read https://model-demand-analytics.vercel.app/api/v1/about first. Use https://model-demand-analytics.vercel.app/api/v1/models for ranked demand and checked model facts. Use https://model-demand-analytics.vercel.app/api/export when you need daily demand history. Use https://model-demand-analytics.vercel.app/api/supply when you need provider supply or supply history. This feed is outside the formal v1 agent schema. Use the website only when the API does not contain the required field.

Preserve null or unavailable values as unknown, not zero. State generated_at, evaluation_cutoff, the data window, freshness, and source limits. Separate direct data from inference. Do not call a model underserved or a supply opportunity from the current data because no approved quantitative rule exists. If the available data cannot answer my question, say so.

My question:
```