---
title: "Usage analytics"
description: "Read billed usage per instance to charge your own users or reconcile your Limrun spend."
canonical_url: "https://docs.limrun.com/docs/platform/usage-analytics"
markdown_url: "https://docs.limrun.com/docs/platform/usage-analytics.md"
last_updated: "2026-11-16"
x_farming_labs_generated_preamble: true
---

# Usage analytics
URL: /docs/platform/usage-analytics
LLM index: /llms.txt
Description: Read billed usage per instance to charge your own users or reconcile your Limrun spend.

# Usage analytics

Use the analytics endpoints to see what each instance cost and which of your users it belongs to. Platforms that run devices for their own customers read them on a schedule and bill those customers by instance label.

There are two endpoints:

- `GET /v1/analytics/instances` returns one entry per billed instance, with its labels and totals.
- `GET /v1/analytics` returns totals per platform and region for each hour, day, week, or minute.

Both need the `analytics` read permission, which every built-in role has. See [Permissions](/docs/reference/permissions). The TypeScript SDK exposes them as `client.analytics.getInstances()` and `client.analytics.get()`. From Python and Go, call the REST endpoints.

## How an instance shows up

An instance shows up only after it terminates and Limrun records its bill. Running instances are not included, and an instance billed for nothing has no entry.

Each instance appears once, with the totals for its whole run. A 10-minute simulator session is a single entry with `runtimeMinutes: 10`. Usage is never split across buckets, and the numbers are not per-bucket increments.

Entries are grouped into minute buckets by the instance's start time. Buckets use the `timezone` parameter, which defaults to `America/Los_Angeles`, so pass `timezone=UTC` if you store times in UTC.

## Fetch instances that stopped in a window

To get every instance that ended between two times, filter on `stoppedAt`. Both bounds are RFC3339 timestamps, and both are inclusive.

<CodeGroup labels={["TypeScript", "cURL"]}>
```ts
const usage = await client.analytics.getInstances({
  stoppedAt: {
    gte: "2026-11-15T10:00:00Z",
    lte: "2026-11-15T10:10:00Z",
  },
  timezone: "UTC",
});

for (const bucket of usage.series) {
  for (const instance of bucket.instances) {
    console.log(instance.instanceTid, instance.labels, instance.runtimeMinutes);
  }
}
```

```bash
curl -G "https://api.limrun.com/v1/analytics/instances" \
  -H "Authorization: Bearer $LIM_API_KEY" \
  --data-urlencode "stoppedAt[gte]=2026-11-15T10:00:00Z" \
  --data-urlencode "stoppedAt[lte]=2026-11-15T10:10:00Z" \
  --data-urlencode "timezone=UTC"
```
</CodeGroup>

In the query string, write the bounds as `stoppedAt[gte]` and `stoppedAt[lte]`. `--data-urlencode` encodes the brackets, and without it curl reads them as a URL pattern. You can also bound the start time with `startedAt[gte]` and `startedAt[lte]`. Every bound you pass applies, and at least one is required.

Two more filters narrow the result:

- `labels` takes `key=value` pairs separated by commas, such as `customer=acme,env=prod`. An instance matches when it has every pair.
- `region` keeps instances from one region, such as `us-east1`.

The response for an Android instance that ran for under a minute looks like this:

```json
{
  "asOf": "2026-11-15T10:20:00.15484819Z",
  "timezone": "UTC",
  "series": [
    {
      "timestamp": "2026-11-15T10:04:00Z",
      "instances": [
        {
          "instanceTid": "android_usw1_01krxvphn8e3rbeq0zewgw209a",
          "platform": "android",
          "region": "us-west1",
          "runtimeMinutes": 1,
          "billedMinutes": 1,
          "billedCredits": "1",
          "wallclockMinutes": 1,
          "cost": 0,
          "labels": {
            "customer": "acme"
          },
          "billedBreakdown": {
            "creditsBilled": "1",
            "creditsBilledMinutes": 1,
            "onDemandBilledCredits": "0",
            "onDemandBilledMinutes": 0
          }
        }
      ]
    }
  ]
}
```

`timestamp` is the minute the instance started. `asOf` is the time the server answered. It does not mean the window is complete.

## Response fields

| Field | Meaning |
|---|---|
| `instanceTid` | The instance ID. Use it as the key when you store entries. |
| `platform` | `android`, `ios`, `xcode`, or `gradle`. |
| `region` | The region the instance ran in. |
| `labels` | The instance's labels when its bill was recorded. |
| `runtimeMinutes` | Runtime minutes before the platform multiplier. |
| `billedCredits` | The exact credits charged, as a decimal string. Prefer it over `billedMinutes`. |
| `billedMinutes` | Billed minutes after the platform multiplier, as a whole number. |
| `wallclockMinutes` | The instance's lifetime in minutes. For Xcode and Gradle builds, `runtimeMinutes` uses phase rates and can be higher or lower than this. Zero for instances billed before the field existed. |
| `cost` | Billed minutes times your plan's per-minute price, in dollars. It is `0` for minutes covered by credits and on some custom-priced plans, so use your invoice for what you owe. |
| `billedBreakdown`, `costBreakdown` | How `billedMinutes` and `cost` split between credits, subscriptions, and on-demand usage. |

<Note>
  The TypeScript SDK's response types do not list `billedCredits` or `wallclockMinutes` yet. Both are in the JSON response.
</Note>

## Import usage on a schedule

To bill your own users every few minutes, fetch fixed windows by `stoppedAt` and wait a while before fetching each one. An instance that just stopped needs a short time to be billed, and it only shows up after that. If a window ends at the current time, it can miss those instances.

For example, a job that runs every 10 minutes fetches the window that ended 10 minutes earlier. The run at 10:20 fetches 10:00 to 10:10, and the run at 10:30 fetches 10:10 to 10:20. Each window is complete when you fetch it, so you fetch it only once.

This function returns the window for a run:

```ts
const WINDOW_MS = 10 * 60 * 1000;

function windowFor(runAt: Date) {
  const end = Math.floor(runAt.getTime() / WINDOW_MS) * WINDOW_MS - WINDOW_MS;
  return {
    gte: new Date(end - WINDOW_MS).toISOString(),
    lte: new Date(end).toISOString(),
  };
}
```

Windows that share a boundary both include an instance that stopped exactly on it. Store entries keyed by `instanceTid` so that instance is counted once.

## Get totals over time

`GET /v1/analytics` adds usage up per platform and region instead of listing instances. `bucket` sets the granularity: `hour`, `day` (the default), `week`, or `minute`. It takes the same time bounds, `labels`, `region`, and `timezone` as the instances endpoint.

<CodeGroup labels={["TypeScript", "cURL"]}>
```ts
const totals = await client.analytics.get({
  startedAt: {
    gte: "2026-11-01T00:00:00Z",
    lte: "2026-11-30T23:59:59Z",
  },
  bucket: "day",
  timezone: "UTC",
});
```

```bash
curl -G "https://api.limrun.com/v1/analytics" \
  -H "Authorization: Bearer $LIM_API_KEY" \
  --data-urlencode "startedAt[gte]=2026-11-01T00:00:00Z" \
  --data-urlencode "startedAt[lte]=2026-11-30T23:59:59Z" \
  --data-urlencode "bucket=day" \
  --data-urlencode "timezone=UTC"
```
</CodeGroup>

Each entry in `series` holds one bucket, with `android`, `ios`, `xcode`, and `gradle` maps from region to totals. `summary` holds the same totals for the whole range. A bounded start-time range, with both `startedAt[gte]` and `startedAt[lte]`, includes empty buckets. Other queries return only the buckets that have usage.

<Note>
  The older `from` and `to` parameters still work. They mean `startedAt >= from` and `startedAt < to`, combine with the other bounds, and are echoed in the response when you pass them.
</Note>

The console's **Analytics** tab shows the same totals as charts.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).
