Llim.run

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:

Both need the analytics read permission, which every built-in role has. See 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.

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);
  }
}
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"

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:

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

{
  "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

FieldMeaning
instanceTidThe instance ID. Use it as the key when you store entries.
platformandroid, ios, xcode, or gradle.
regionThe region the instance ran in.
labelsThe instance's labels when its bill was recorded.
runtimeMinutesRuntime minutes before the platform multiplier.
billedCreditsThe exact credits charged, as a decimal string. Prefer it over billedMinutes.
billedMinutesBilled minutes after the platform multiplier, as a whole number.
wallclockMinutesThe 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.
costBilled 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, costBreakdownHow billedMinutes and cost split between credits, subscriptions, and on-demand usage.

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

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:

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.

const totals = await client.analytics.get({
  startedAt: {
    gte: "2026-11-01T00:00:00Z",
    lte: "2026-11-30T23:59:59Z",
  },
  bucket: "day",
  timezone: "UTC",
});
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"

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.

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.

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