Quickstart
Pull your account's results and the token usage behind them, using nothing but HTTP requests.
On this page
This walks through one useful end-to-end task: list what your account holds, then pull the token usage that accounts for it. Those two answers together are what most reporting and cost allocation work is built on.
You will need a RunDiffusion account. The reporting half additionally needs an Enterprise plan; everything else works on any plan.
1. Get your credentials
Which one you need is decided by the endpoint you are calling and by who the work belongs to.
| Credential |
|---|
| OAuth device flowAn ID token from the RFC 8628 device code flow. Works for personal and team calls alike, so it is the alternative to either token. |
| Personal API Access TokenFor personal plans. A long-lived key that acts as you on your personal account: your library, boards, uploads, and generations. |
| Company API Access TokenFor team and enterprise plans. A long-lived key that acts as you on your company's teams, plus company usage reporting. |
A Public API Access Token is a long-lived key from the Plugins & APIs page. On a personal plan you create a Personal token yourself. On a team or enterprise plan, an account administrator creates a Company token and associates it to your user. Both act as you, so anything they do is attributed to you.
The OAuth token comes from the device flow and works for either. Prefer it when a real person signs in to an app you distribute. Authentication has the full walkthrough for both.
Put them in your environment so the rest of the steps can read them:
export RUNDIFFUSION_API_TOKEN="<your Public API Access Token>"
export RUNDIFFUSION_TOKEN="<token from the OAuth device flow>"2. Confirm your token works
The fastest check is to ask the API who you are.
curl https://api2.rundiffusion.com/api/v2/me \
-H "Authorization: Bearer $RUNDIFFUSION_TOKEN"const me = await fetch('https://api2.rundiffusion.com/api/v2/me', {
headers: { Authorization: `Bearer ${process.env.RUNDIFFUSION_TOKEN}` },
}).then(r => r.json());
console.log(me);import os
import requests
BASE = "https://api2.rundiffusion.com/api/v2"
HEADERS = {"Authorization": f"Bearer {os.environ['RUNDIFFUSION_TOKEN']}"}
me = requests.get(f"{BASE}/me", headers=HEADERS).json()
print(me)A 401 here means the token is wrong or expired. Anything else and you are ready
to continue.
Keep the accounts array from that response. Each entry has an id, and it tells
you what to send on account-scoped requests: a team's id goes in the team_id
query parameter, and sending no team_id acts on the caller's individual
account. See Identity.
3. List what your account holds
The library is the generations on your account, newest first. One request gets you a page of it.
curl -G https://api2.rundiffusion.com/api/v2/library \
-H "Authorization: Bearer $RUNDIFFUSION_TOKEN" \
--data-urlencode "limit=24"const page = await fetch(
'https://api2.rundiffusion.com/api/v2/library?limit=24',
{ headers: { Authorization: `Bearer ${process.env.RUNDIFFUSION_TOKEN}` } },
).then(r => r.json());
for (const item of page.data) {
console.log(item.id, item.type, item.created);
}page = requests.get(
f"{BASE}/library",
headers=HEADERS,
params={"limit": 24},
).json()
for item in page["data"]:
print(item["id"], item["type"], item["created"])Each item carries its type, its dimensions, and a signed url you can download.
Those URLs expire after roughly seven days, so treat them as short-lived and
re-list rather than storing them. See Library.
4. Pull the usage behind it
Reporting answers the other half: what that activity cost. It returns one row per balance record rather than a pre-aggregated total, so you can group it however your business actually works.
Note the different credential here.
curl -G https://api2.rundiffusion.com/api/v2/reporting/token-usage \
-H "Authorization: Bearer $RUNDIFFUSION_API_TOKEN" \
--data-urlencode "start_utc=2026-07-01T00:00:00Z" \
--data-urlencode "end_utc=2026-08-01T00:00:00Z" \
--data-urlencode "limit=1000"const params = new URLSearchParams({
start_utc: '2026-07-01T00:00:00Z',
end_utc: '2026-08-01T00:00:00Z',
limit: '1000',
});
const usage = await fetch(
`https://api2.rundiffusion.com/api/v2/reporting/token-usage?${params}`,
{ headers: { Authorization: `Bearer ${process.env.RUNDIFFUSION_API_TOKEN}` } },
).then(r => r.json());
const total = usage.data.reduce((sum, row) => sum + row.total_tokens, 0);
console.log(usage.data.length, 'rows,', total, 'tokens');REPORTING_HEADERS = {
"Authorization": f"Bearer {os.environ['RUNDIFFUSION_API_TOKEN']}"
}
usage = requests.get(
f"{BASE}/reporting/token-usage",
headers=REPORTING_HEADERS,
params={
"start_utc": "2026-07-01T00:00:00Z",
"end_utc": "2026-08-01T00:00:00Z",
"limit": 1000,
},
).json()
total = sum(row["total_tokens"] for row in usage["data"])
print(len(usage["data"]), "rows,", total, "tokens")5. Page through everything
Both endpoints use the same cursor pattern, so one helper covers both: follow
next_cursor until has_more is false.
async function* allPages(url, headers, params = {}) {
let cursor;
while (true) {
const query = new URLSearchParams({ ...params });
if (cursor) query.set('cursor', cursor);
const page = await fetch(`${url}?${query}`, { headers }).then(r => r.json());
yield* page.data;
if (!page.has_more || !page.next_cursor) return;
cursor = page.next_cursor;
}
}
const headers = { Authorization: `Bearer ${process.env.RUNDIFFUSION_API_TOKEN}` };
for await (const row of allPages(
'https://api2.rundiffusion.com/api/v2/reporting/token-usage',
headers,
{ start_utc: '2026-07-01T00:00:00Z', end_utc: '2026-08-01T00:00:00Z' },
)) {
console.log(row.record_id, row.total_tokens);
}def all_pages(path, headers, params=None):
params = dict(params or {})
cursor = None
while True:
if cursor:
params["cursor"] = cursor
page = requests.get(f"{BASE}{path}", headers=headers, params=params).json()
yield from page["data"]
cursor = page.get("next_cursor")
if not page.get("has_more") or not cursor:
return
for row in all_pages(
"/reporting/token-usage",
REPORTING_HEADERS,
{"start_utc": "2026-07-01T00:00:00Z", "end_utc": "2026-08-01T00:00:00Z"},
):
print(row["record_id"], row["total_tokens"])