What you’re setting up

UsageFlow is AI runtime billing infrastructure: it meters AI and API usage in your app runtime, enforces spend limits before costly work executes, and can sync usage to Stripe. See AI usage metering and AI agent meter platform for the product pillars.

Meter · enforce · bill. This guide gets you to a verified Trace. Policy enforcement and Stripe sync happen next in Console — after the agent is live.

Snippets match the Console Knowledge Base Quick Start. Keep Console docs as the source of truth when packages change.

Six steps to a Trace

  1. Install the package for your framework
  2. Set USAGEFLOW_API_KEY in the environment
  3. Register the middleware / plugin / module before your routes
  4. In Console → Application → Configuration, add explicit monitoringPaths and whitelistEndpoints
  5. Send a test request
  6. Open Traces for the same application and confirm the request (see NestJS note below)

Create the API key in the UsageFlow Console. Do not commit it.

export USAGEFLOW_API_KEY="your-api-key"

Install the agent

Supported packages today:

npm install @usageflow/express npm install @usageflow/fastify npm install @usageflow/nestjs pip install usageflow-flask pip install usageflow-fastapi uvicorn go get github.com/usageflow/usageflow-go-middleware/v2

Register before routes

Prefer framework packages over core. Register UsageFlow before application routes (and after body parsers where your framework needs them).

Express

import express from "express"; import { ExpressUsageFlowAPI } from "@usageflow/express"; const apiKey = process.env.USAGEFLOW_API_KEY; if (!apiKey) throw new Error("Missing USAGEFLOW_API_KEY"); const app = express(); app.use(express.json()); const usageFlow = new ExpressUsageFlowAPI(apiKey); app.use(usageFlow.createMiddleware()); app.get("/api/users", (_req, res) => res.json([]));

Fastify

import Fastify from "fastify"; import { FastifyUsageFlowAPI } from "@usageflow/fastify"; const apiKey = process.env.USAGEFLOW_API_KEY; if (!apiKey) throw new Error("Missing USAGEFLOW_API_KEY"); const app = Fastify(); const usageFlow = new FastifyUsageFlowAPI(apiKey); await app.register(usageFlow.createPlugin()); app.get("/api/users", async () => []);

NestJS

import { Module } from "@nestjs/common"; import { UsageFlowModule } from "@usageflow/nestjs"; const apiKey = process.env.USAGEFLOW_API_KEY; if (!apiKey) throw new Error("Missing USAGEFLOW_API_KEY"); @Module({ imports: [UsageFlowModule.forRoot({ apiKey })], }) export class AppModule {}
NestJS limitation: module registration alone does not start request processing reliably today, so NestJS request traces are not currently supported. Prefer Express or Fastify where you need Traces.

Flask

import os from flask import Flask from usageflow.flask import UsageFlowMiddleware app = Flask(__name__) UsageFlowMiddleware(app, api_key=os.environ["USAGEFLOW_API_KEY"]) @app.get("/api/users") def users(): return []

FastAPI

import os from fastapi import FastAPI from usageflow.fastapi import UsageFlowMiddleware app = FastAPI() app.add_middleware( UsageFlowMiddleware, api_key=os.environ["USAGEFLOW_API_KEY"], ) @app.get("/api/users") def users(): return []
Start with uvicorn app:app. Do not enable this middleware on routes that depend on FastAPI / Starlette response background tasks — the current middleware replaces an existing response background task.

Gin (Go v2)

package main import ( "log" "os" "github.com/gin-gonic/gin" "github.com/usageflow/usageflow-go-middleware/v2/pkg/middleware" ) func main() { apiKey := os.Getenv("USAGEFLOW_API_KEY") if apiKey == "" { log.Fatal("Missing USAGEFLOW_API_KEY") } router := gin.New() usageFlow := middleware.New(apiKey) router.Use(usageFlow.RequestInterceptor()) router.GET("/api/users", func(c *gin.Context) { c.JSON(200, []string{}) }) if err := router.Run(":8080"); err != nil { log.Fatal(err) } }

Configure routes to meter

Route selection lives in Console — not hard-coded in your app. Open the application that owns the API key → Configuration, then set:

Add explicit patterns so behavior stays clear across runtimes. Empty monitoringPaths differs by runtime: Node and Go currently monitor all routes; current Python middleware skips all routes when empty. After changes, allow about 10 seconds (Node/Python) or 30 seconds (Go) for the agent to refresh.

Verify in Traces

# Express / Fastify / NestJS (typical) curl -i http://localhost:3000/api/users # Flask curl -i http://localhost:5000/api/users # FastAPI curl -i http://localhost:8000/api/users # Gin curl -i http://localhost:8080/api/users

In Console, select the same application and open Traces. Confirm the request appears. If nothing shows: check the key, selected app, middleware order, and monitoringPaths.

Next: enforce spend and sync to Stripe

Once Traces prove the agent is live, use Console to enforce spend before execution and — when you bill customers — configure a Stripe API key in Integrations so UsageFlow can fire meter events. See the Stripe integration guide and AI payment infrastructure.

FAQ

What is UsageFlow?

UsageFlow is AI runtime billing infrastructure. It meters AI and API usage in your app runtime, enforces spend limits before costly work executes, and can sync usage to Stripe.

Where do I configure which routes to meter?

In Console → Application → Configuration. Set monitoringPaths (routes to meter) and whitelistEndpoints (routes to skip). Do not hard-code route lists in your agent install.

Why don’t I see a Trace?

Check the API key, that you selected the same application in Console, middleware order (before routes), and that monitoringPaths includes the request pattern. NestJS request traces are not currently supported.

Does this replace Stripe?

No. Stripe remains the system of record for invoices and charges. UsageFlow meters in runtime and reports meter events when you configure a Stripe API key in Console → Integrations.