PARAS MADAN
All writing

Latest in AI

Runway Request Tags: Track Campaign Credits Without Double Counting

A practical tagging plan for Runway API credit reporting, with campaign ownership, safe header handling and a reconciliation check before client billing.

A creative pipeline can produce work for three clients and still leave finance with one unexplained bill. The missing information is often not the model or the output. It is who requested the work and which campaign should pay for it.

Runway's November 18 update adds X-Runway-Tags to generation requests and tag-based filtering and breakdowns to POST /v1/organization/usage. Workflow runs pass their tags to the generations they start, and the Developer Portal exposes the breakdown too. Runway's changelog documents the release.

The useful implementation is a small accounting contract between your application and whoever reviews spending. Here is a proposed workflow, not a report from a live deployment.

Decide who owns each generation

Start with the question your monthly report must answer. For an agency, I would choose one internal project identifier, one campaign identifier and an environment. Avoid turning tags into a second copy of your job database.

An illustrative header could be:

X-Runway-Tags: project:p042,campaign:launch07,env:prod

Keep the mapping from p042 to the customer's name in your own system. The reporting label should be useful without exposing the customer. Runway specifically warns against putting personal data in tags.

Give the application responsibility for assigning these values. A free-text campaign field lets small spelling differences create separate accounting categories, even when everyone believes they are working on the same launch.

Build one complete header

Runway's request-level tag header replaces client defaults rather than merging with them. Its request-tags guide also documents the reporting behavior below.

My recommendation is to assemble the complete header in one application function. Pass that function an approved project, campaign and environment, and reject an incomplete assignment before submitting paid work.

Test the assembled string locally before connecting the wrapper to paid generation. Include a missing campaign, an unknown project and a request from your staging environment. These are application validation checks, not model quality tests.

Also test the route that handles retries. An unsuccessful creative attempt still belongs to somebody's project; a retry should not quietly become an unassigned internal expense in your own records.

Choose a partition, not a pile of labels

With groupBy: "tag", one generation contributes to every matching tag bucket. Summing those buckets can overstate spending. Use a keyed breakdown such as groupBy: "tag:project" for allocation. Missing keys appear under null.

For illustration only, suppose a fictional job costs 100 credits and carries three labels. Three overlapping 100-credit categories do not represent 300 credits of work. This is arithmetic, not a Runway price quote.

In your application, require exactly one project assignment per job. A report should not have to guess which client owns a generation. Treat conflicting assignments as a data-quality failure to fix at the point of submission.

Separate reconciliation from invoicing

Usage refreshes hourly. Query windows use UTC dates and an exclusive beforeDate. Amounts are net credits and can be negative after refunds. These reports cover API-project usage, not web-app workspace spending.

I would keep a reconciliation sheet with four columns: reporting window, provider total, allocated total and unresolved difference. Record when each snapshot was taken so a later refresh does not look like an unexplained correction.

Put unassigned spending into a review queue rather than spreading it proportionally across clients. Otherwise, one forgotten label becomes an invisible surcharge on everybody else's work.

Your commercial invoice needs its own rules for revisions, internal experiments and client-approved work. Decide those rules before connecting a usage export to an invoicing system.

Make the first rollout deliberately small

Choose one campaign and one person responsible for reviewing it. Before widening the rollout, ask that person to explain a sample expense using both the reporting label and your internal job record.

If they cannot trace it back to a real request, adding more tags will not fix the problem. Correct the ownership mapping first. The goal is a bill someone can explain without asking an engineer to reconstruct the month.

I'm Paras. I work at the intersection of AI, engineering and distribution.

I help AI teams explain technical products through clear documentation, practical guides and developer-focused content.

Book a 30-minute call.