Knowledge BaseJanuary 2026

UsageFlow Knowledge Base

Everything you need to know about UsageFlow, from core concepts to integration guides. Get started in minutes, not days.

What is UsageFlow?

UsageFlow is a powerful API usage tracking and management platform that helps you monitor, control, and optimize your API usage across different frameworks and languages. It's designed to make API metering so simple that setup takes minutes, not days.

UsageFlow provides framework-native packages for popular web frameworks, eliminating the need for complex configuration. The platform automatically discovers your API endpoints, tracks usage in real-time, and provides comprehensive analytics and control mechanisms.

Key Features:

Key Features:

✓Framework-Native Packages: Dedicated packages for Express, Fastify, NestJS, FastAPI, Flask, and Gin that feel like they were built specifically for your framework
✓Zero Configuration: Automatic endpoint discovery - no need to manually register routes or define which endpoints to track
✓Minimal Latency: Adds just 50ms of latency per request, running alongside your application without dedicated servers
✓Real-Time Tracking: Monitor API usage, response times, error rates, and more in real-time
✓Rate Limiting: Built-in rate limiting capabilities to protect your APIs
✓Metering & Monetization: Track usage and integrate with billing systems like Stripe

What is an Endpoint?

An endpoint in UsageFlow represents a specific API route or URL path in your application that can receive HTTP requests. Each endpoint is identified by:

Each endpoint is identified by:

•HTTP Method: GET, POST, PUT, DELETE, PATCH, etc.
•URL Pattern: The path pattern that matches the endpoint (e.g., /api/users/:id)
•Application: The application or service that hosts the endpoint

UsageFlow automatically discovers endpoints in your application by monitoring incoming requests. Once discovered, you can:

Once discovered, you can:

→View detailed analytics and metrics for each endpoint
→Apply policies to control access and usage
→Set up rate limiting
→Configure metering for billing and monetization
→Monitor performance, error rates, and response times

💡 Example

If your API has a route GET /api/users, UsageFlow will automatically discover it and start tracking requests to that endpoint.

What is a Strategy?

A Strategy in UsageFlow defines how to identify and extract user or customer identity from incoming API requests. It specifies:

A strategy specifies:

•Identity Field Name: The name of the field that contains the user/customer identifier (e.g., userId, customerId, apiKey)
•Identity Field Location: Where to look for this field - in the request headers, query parameters, or request body

Strategies are reusable configurations that can be applied to multiple policies. This allows you to:

Strategies allow you to:

→Consistently identify users across different endpoints
→Track usage per user or customer
→Apply rate limits and quotas on a per-user basis
→Enable metering and billing for specific customers

💡 Example

A strategy might extract the userId from the X-User-Id header. This strategy can then be used in policies to track usage per user.

What is a Policy?

A Policy in UsageFlow is a set of rules and configurations that control how a specific endpoint (or group of endpoints) behaves. Policies combine:

Policies combine:

•Endpoint Pattern: Which endpoints the policy applies to (e.g., /api/users/*)
•HTTP Method: The specific HTTP method(s) the policy applies to
•Strategy: How to identify the user/customer making the request
•Rate Limiting: Optional rate limits to control request frequency
•Metering: Optional configuration for tracking usage and billing

Policies allow you to:

→Apply different rules to different endpoints
→Control access and usage on a per-user or per-customer basis
→Enforce rate limits to protect your API from abuse
→Enable metering for billing and monetization
→Integrate with billing systems like Stripe

💡 Example

A policy might apply to POST /api/transactions, use a strategy to identify customers, enforce a rate limit of 100 requests per hour, and enable Stripe metering for billing.

How We Meter

🚀 Zero Code Required

Just install the middleware — all configuration is done from the UsageFlow console. No additional code changes needed in your application. UsageFlow handles everything behind the scenes.

Getting Started

1.Install the middleware — Add the UsageFlow package to your app (one-time setup, see installation guides below)
2.Configure in console — Set up your strategies, policies, and Stripe integration in the UsageFlow console
3.Done! — Usage is automatically tracked and reported to Stripe

What You Configure in the Console

→Strategy: How to identify customers making requests (JWT, API Key, or custom header)
→Tracked Endpoints: Which API routes to meter (see Route Configuration)
→Policy: Which Stripe meter to report usage to

What UsageFlow Does For You

✓Tracks usage on your configured endpoints
✓Identifies customers based on your strategy
✓Reports usage to Stripe automatically
✓Provides analytics and usage insights in the console

💡 That's It!

Once the middleware is installed, you never need to touch your code again. All changes to metering, billing, and policies are made in the UsageFlow console and take effect immediately.

Route Configuration

⚠️ Important: Default Behavior

By default, UsageFlow does not monitor any routes. You must explicitly configure which endpoints you want to track for metering and billing. This gives you complete control over what gets monitored.

After installing the UsageFlow SDK, you need to configure which API routes should be tracked and which should be excluded. This is done through the Application Configuration in the UsageFlow console.

Tracked Endpoints (Usage & Billing)

These are the API routes that UsageFlow will actively monitor, track, and meter for billing purposes. Only requests matching these paths will be tracked.

✓Add specific routes you want to meter (e.g., /api/v1/chat/*)
✓Use * as a wildcard for any path segment
✓Use {paramName} for path parameters
✓Choose HTTP methods (GET, POST, PUT, DELETE, etc.) or * for all methods

Tip: Use * * (method: *, path: *) to track all endpoints — but be aware this includes internal/admin routes.

Excluded Endpoints (Not Tracked)

These are routes that should be excluded from usage tracking and billing. Exclusions take precedence over tracked endpoints, allowing you to create broad tracking rules with specific exceptions.

✗Health check endpoints (e.g., /api/health)
✗Internal admin routes (e.g., /api/admin/*)
✗Documentation endpoints (e.g., /api/docs/*)
✗Any routes that shouldn't count toward customer usage

How to Configure Routes

1.Navigate to Management in the UsageFlow console
2.Select your application
3.Open the Application Configuration section
4.Add endpoint patterns to Tracked Endpoints — these will be metered
5.Add endpoint patterns to Excluded Endpoints — these will be skipped
6.Click Confirm to save your configuration

Pattern Examples

Pattern	Matches
`GET /api/users`	Exact match for GET /api/users
`* /api/v1/*`	Any method on any path under /api/v1/
`POST /api/chat/{id}`	POST to /api/chat/ with any ID parameter
`* *`	All methods on all paths (track everything)

💡 Best Practice

Start by adding specific routes you want to bill for, such as POST /api/v1/generate. Then exclude any internal routes like health checks. This approach ensures you only meter actual customer usage.

Quick Start

Choose your framework below to get started with UsageFlow integration:

Node.js Frameworks

Install the UsageFlow package for your Node.js framework:

@usageflow/express @usageflow/fastify @usageflow/nestjs

Bash

# For Express.js
npm install @usageflow/express

# For Fastify
npm install @usageflow/fastify

# For NestJS
npm install @usageflow/nestjs

Express.js

JavaScript

import express from 'express';
import { ExpressUsageFlowAPI } from '@usageflow/express';

const app = express();
const port = process.env.PORT || 4001;

// Initialize UsageFlow
const usageFlow = new ExpressUsageFlowAPI('YOUR_API_KEY');;

// Create middleware
app.use(usageFlow.createMiddleware());

// Your routes here
app.get('/api/users', (req, res) => {
  res.json([{ id: 1, name: 'John Doe' }]);
});

Fastify

JavaScript

import fastify from 'fastify';
import { FastifyUsageFlowAPI } from '@usageflow/fastify';

const app = fastify();
// Initialize UsageFlow with API key
const usageFlow = new FastifyUsageFlowAPI('YOUR_API_KEY');

// Register UsageFlow plugin
app.register(usageFlow.createPlugin());
);

NestJS

TypeScript

import { Module } from '@nestjs/common';
import { Module } from '@nestjs/common';
import { UsageFlowModule } from '@usageflow/nestjs';

@Module({
  imports: [
    UsageFlowModule.forRoot({
      apiKey: 'YOUR_API_KEY',
    }),
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

Python Frameworks

Install the UsageFlow package for your Python framework:

usageflow-fastapi usageflow-flask

Bash

# For FastAPI
pip install usageflow-fastapi

# For Flask
pip install usageflow-flask

FastAPI

Python

from fastapi import FastAPI
from usageflow.fastapi import FastAPIUsageFlowAPI

app = FastAPI()
usage_flow = FastAPIUsageFlowAPI()

# Initialize UsageFlow
usage_flow.init('YOUR_API_KEY')

# Create middleware
middleware = usage_flow.request_interceptor(
    routes=[{'method': '*', 'url': '*'}],
    whitelist_routes=[{'method': 'GET', 'url': '/api/health'}]
)

# Add middleware to app
app.add_middleware(middleware)

Flask

Python

from flask import Flask
from usageflow.flask import FlaskUsageFlowAPI

app = Flask(__name__)
usage_flow = FlaskUsageFlowAPI()

# Initialize UsageFlow
usage_flow.init('YOUR_API_KEY')

# Create and apply middleware
middleware = usage_flow.request_interceptor(
    routes=[{'method': '*', 'url': '*'}],
    whitelist_routes=[{'method': 'GET', 'url': '/api/health'}]
)
middleware(app)

Go

Install the UsageFlow middleware package for Go (Gin framework):

usageflow-go-middleware GitHub

Bash

# Install UsageFlow Go middleware package
go get -u github.com/usageflow/usageflow-go-middleware/v2

Gin Framework

The Go middleware provides request interception, usage tracking, user identification, and automatic configuration updates with graceful degradation.

package main

import (
    "github.com/gin-gonic/gin"
    "github.com/usageflow/usageflow-go-middleware/v2/pkg/middleware"
)

func main() {
    app := gin.New()

    // Create new UsageFlowAPI instance
    // This initializes WebSocket connection pool and starts config updater
    usageAPI := middleware.New("YOUR_API_KEY")

    // Apply the request interceptor middleware
    // Routes and whitelist are configured via the dashboard
    app.Use(usageAPI.RequestInterceptor())

    // Your routes here
    app.GET("/api/users", func(c *gin.Context) {
        c.JSON(200, gin.H{"users": []string{"John", "Jane"}})
    })

    app.Run(":8080")
}

Best Practices

API Key Security

Never commit API keys to version control. Always use environment variables.

Route Organization

Group similar endpoints under common prefixes
Use consistent naming conventions
Document route patterns clearly

Resources & Support

Find packages, examples, and get help:

GitHub

github.com/usageflow

npm Packages

@usageflow/express, @usageflow/fastify, @usageflow/nestjs

PyPI Packages

usageflow-fastapi, usageflow-flask

Go Package

usageflow-go-middleware

Need help? Contact our support team:

Email: [email protected]