# Usage Monitoring Tools (/docs/usage-monitoring)


Yunxin records every request — tokens, cost, latency, time-to-first-token, routing, and any fallback —
in your usage history. You can read that data two ways: through Yunxin's **native analytics endpoints**,
or through a set of **monitoring-tool-compatible shells** that mimic other providers' usage APIs so
existing dashboards and CLIs work against Yunxin unmodified.

All endpoints below return **your own** data and require your API key (the same `sk-` key you use for
inference), unless noted as public. Send it as `Authorization: Bearer $YUNXIN_API_KEY`.

## Native analytics [#native-analytics]

Use these when you're building your own dashboards or scripts against Yunxin directly.

| Endpoint                             | Returns                                     |
| ------------------------------------ | ------------------------------------------- |
| `GET /v1/analytics/usage/summary`    | Aggregate usage and cost over a period.     |
| `GET /v1/analytics/usage/by-model`   | Usage and cost broken down per model.       |
| `GET /v1/analytics/usage/timeseries` | Usage over time, bucketed for charts.       |
| `GET /v1/billing/usage`              | Billing-oriented usage and current balance. |

```bash
curl https://api.yuhuanstudio.com/v1/analytics/usage/summary \
  -H "Authorization: Bearer $YUNXIN_API_KEY"
```

<Callout type="info">
  Costs are reported in credits, where **1 credit = $0.001 USD**. See [Pricing & Billing](/docs/pricing)
  for how per-request cost is computed.
</Callout>

### Public stats [#public-stats]

`GET /v1/stats/public` needs **no authentication** and returns platform-level facts (model and provider
counts, uptime) — handy for status pages.

```bash
curl https://api.yuhuanstudio.com/v1/stats/public
```

## Monitoring-tool-compatible shells [#monitoring-tool-compatible-shells]

Popular "API usage" dashboards and CLIs (for example **openusage** and **cc-switch**) only know how to
read a handful of providers' usage APIs. Rather than ask you to modify those tools, Yunxin exposes the
same response shapes those tools expect. Point the tool at Yunxin as if it were that provider, give it
your `sk-` key, and your real Yunxin balance and usage show up — no tool changes required.

| Shape           | Endpoint(s)                                                | Returns                                                            |
| --------------- | ---------------------------------------------------------- | ------------------------------------------------------------------ |
| **OpenRouter**  | `GET /v1/credits`, `GET /v1/key`, `GET /v1/activity?days=` | Credits/usage, key metadata, per-day per-model activity.           |
| **SiliconFlow** | `GET /v1/user/info`                                        | `{ "data": { "balance", "totalBalance", "chargeBalance", ... } }`. |
| **DeepSeek**    | `GET /user/balance`                                        | `{ "is_available", "balance_infos": [ ... ] }`.                    |
| **Novita**      | `GET /openapi/v1/billing/balance/detail`                   | `{ "availableBalance", ... }` (balance unit is 1/10000 USD).       |
| **z.ai**        | `GET /api/monitor/usage/quota/limit`                       | Monthly token quota as a percentage bucket.                        |

<Callout type="info">
  The DeepSeek, Novita, and z.ai shapes live at the **root** of the domain (not under `/v1`), matching
  those providers' real paths. The OpenRouter `/credits`, `/key`, and `/activity` routes are reachable
  under both `/v1/...` and `/api/v1/...`.
</Callout>

### OpenRouter shape [#openrouter-shape]

The OpenRouter `credits` endpoint reports lifetime spend and your balance, so any tool that computes
`total_credits − total_usage` shows your real remaining balance:

```bash
curl https://api.yuhuanstudio.com/v1/credits \
  -H "Authorization: Bearer $YUNXIN_API_KEY"
```

```json
{ "data": { "total_credits": 5000, "total_usage": 1234 } }
```

`GET /v1/key` returns the calling key's label, usage, tier, and rate limit. `GET /v1/activity?days=30`
returns per-day, per-model usage for charts.

## Connecting common tools [#connecting-common-tools]

<Steps>
  <Step>
    ### openusage / cc-switch as an OpenRouter account [#openusage--cc-switch-as-an-openrouter-account]

    Add an OpenRouter-type account, set its base URL to `https://api.yuhuanstudio.com/v1` (or
    `https://api.yuhuanstudio.com/api/v1`), and use your `sk-` key. The tool reads `/credits`, `/key`, and
    `/activity`.
  </Step>

  <Step>
    ### cc-switch as DeepSeek / SiliconFlow / Novita / z.ai [#cc-switch-as-deepseek--siliconflow--novita--zai]

    Add a provider of that type, point its base URL at `https://api.yuhuanstudio.com`, and use your `sk-`
    key. The tool reads that provider's balance endpoint and displays your Yunxin balance inline.
  </Step>
</Steps>

<Callout type="warn">
  These shells are compatibility surfaces, not full reimplementations of each provider's API — they cover
  the balance/usage fields monitoring tools read. For complete, stable data, prefer the native analytics
  endpoints above.
</Callout>

## What gets recorded [#what-gets-recorded]

Every request is logged with its token counts, computed cost, latency and time-to-first-token, the
resolved routing decision, and whether a fallback was used. This is the data the endpoints above
surface, and the same data backing the Dashboard's analytics views. See
[Fallback & Routing](/docs/streaming) for the routing and fallback headers attached to each
response.