Skip to content

Send X-Runway-Tags on a request to label the credits it spends. You can then filter and break down POST /v1/organization/usage by those labels, or do the same from the Usage page in the Developer Portal.

Use tags for the dimensions you already reconcile on: a team, an environment, a campaign, a customer project.

The header is a comma-separated list of up to 10 tags. Each tag is a plain label (campaign-q4) or a key:value pair (team:growth). A pair splits on the first colon, so region:us:west is the key region and the value us:west.

Tags are case-insensitive and stored lowercase. Spaces around a comma are ignored, and a repeated tag is stored once. Each tag is at most 64 characters, using letters, numbers, and _, -, ., /, and :. A key:value tag needs both a key and a value. The whole header is at most 1,024 characters. A tag outside those rules rejects the request with 400, before a generation starts.

The header applies to requests that start work: direct model calls, Model Router calls, recipes, character video and realtime sessions, voice creation, and Workflow runs.

Terminal window
curl -X POST https://api.dev.runwayml.com/v1/image_to_video \
-H "Authorization: Bearer $RUNWAYML_API_SECRET" \
-H "X-Runway-Version: 2024-11-06" \
-H "X-Runway-Tags: team:growth,env:prod,campaign-q4" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance2_5",
"promptImage": "https://upload.wikimedia.org/wikipedia/commons/8/85/Tour_Eiffel_Wikimedia_Commons_(cropped).jpg",
"promptText": "A timelapse on a sunny day with clouds flying by",
"ratio": "1280:720",
"duration": 5
}'

To put the same tags on every call from one client, set the header when you construct it: defaultHeaders in Node, default_headers in Python. A per-request X-Runway-Tags value replaces that default for the call, so repeat any tag you still want on that request.

A tag on POST /v1/workflows/{id} is copied onto every generation that run starts. Tag the run once. See Running a Workflow.

POST /v1/organization/usage returns this project’s credit usage by model and day, for a window of up to 90 days. These totals are what the API project spent. Web app workspace usage is a separate export: Workspace reporting. startDate and beforeDate are UTC dates, and beforeDate is exclusive. Usage updates hourly, so recent activity may not appear yet.

Two fields read tags. tags counts only generations that carry every listed tag (up to 10, case-insensitive). groupBy is case-insensitive too, and adds a resultsByTag breakdown next to the results totals for those same generations:

  • "tag" makes one bucket per tag. A generation with several tags counts toward each of them, so the buckets can add up to more than results.
  • "tag:team" (any key) makes one bucket per value of that key. Each generation counts once, under its team:<value> tag. Two values for the same key on one generation count once, under the alphabetically first value. A generation with no tag for that key is reported with "tag": null.

When you set tags or groupBy, the response also includes tags: the tags on usage in the window, sorted alphabetically, at most the 1,000 with the most credits. That list covers the window, including tags outside the tags filter, so you can see what else was used. amount is net credits for that tag that day, and is negative when refunds exceed charges.

tags keeps generations that carry every listed tag. A generation tagged team:growth,env:prod,campaign-q4 matches ["team:growth", "env:prod"]. This query keeps production usage, then splits those credits by the team key:

Terminal window
curl https://api.dev.runwayml.com/v1/organization/usage \
-H "Authorization: Bearer $RUNWAYML_API_SECRET" \
-H "X-Runway-Version: 2024-11-06" \
-H "Content-Type: application/json" \
-d '{
"startDate": "2026-11-01",
"beforeDate": "2026-12-01",
"tags": ["env:prod"],
"groupBy": "tag:team"
}'
{
"resultsByTag": [
{
"date": "2026-11-17",
"usedCredits": [
{ "tag": "team:growth", "amount": 480 },
{ "tag": "team:brand", "amount": 90 },
{ "tag": null, "amount": 20 }
]
}
],
"tags": ["campaign-q4", "env:prod", "team:brand", "team:growth"]
}

team:growth and team:brand are production generations that carried that key. The null bucket is production usage with no team tag. Leave groupBy out when you only want the filtered results totals. Leave tags out when you want every generation in the window, including untagged ones.

The Usage page filters by API key, model, and tag, and groups the chart by total, model, tag, or one tag key. The chart and the CSV export follow that selection. It reads the same credit usage as POST /v1/organization/usage.