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/instancesreturns one entry per billed instance, with its labels and totals.GET /v1/analyticsreturns 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. 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:
labelstakeskey=valuepairs separated by commas, such ascustomer=acme,env=prod. An instance matches when it has every pair.regionkeeps instances from one region, such asus-east1.
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
| 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. |
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.
Read billed usage per instance to charge your own users or reconcile your Limrun spend.
Was this guide helpful?