Trough Docs

API cost monitor. Track request counts, latency, and estimated cost for any HTTP API.

Overview

API cost monitor. Track request counts, latency, and estimated cost for any HTTP API. License: Apache 2.0. Default port: 8790.

Part of the Stockyard family of developer tools. See the product page →

Install

curl -fsSL https://stockyard.dev/trough/install.sh | sh

Or download a release binary from GitHub Releases.

Quickstart

# Install
curl -fsSL https://stockyard.dev/trough/install.sh | sh

# Run
TROUGH_ADMIN_KEY=secret trough

# Register an upstream
curl -s -X POST http://localhost:8790/api/upstreams \
  -H 'Authorization: Bearer secret' \
  -H 'Content-Type: application/json' \
  -d '{"name":"sendgrid","base_url":"https://api.sendgrid.com"}'

# Add a cost rule (cost in cents)
curl -s -X POST http://localhost:8790/api/upstreams/{id}/rules \
  -H 'Authorization: Bearer secret' \
  -d '{"path_pattern":"/v3/mail/send","cost_cents":1}'

# Use the proxy URL instead of the API directly
# http://localhost:8790/proxy/{upstream_id}/v3/mail/send

# Check spend
curl -s http://localhost:8790/api/spend -H 'Authorization: Bearer secret'

Environment Variables

Variable	Description	Default
PORT	HTTP listen port	8790
DATA_DIR	SQLite data directory	./data
TROUGH_ADMIN_KEY	Admin API key

API Reference

GET/api/upstreams

List registered upstreams

POST/api/upstreams

POST/api/upstreams/{id}/rules

Add a cost rule to an upstream

GET/api/spend

Spend summary (by day, by endpoint)

GET/api/requests

Raw request log

GET/api/export.csv

Download cost report as CSV

POST/api/alerts

Create a spend alert

GET/api/stats

Overall stats

GET/proxy/{upstream_id}/{path...}

Proxy to upstream (records cost)

GET/health

Health check

Note — Admin endpoints require Authorization: Bearer <admin-key>. The admin key is set via the environment variable for this tool.

Deployment

Run the binary directly or use the provided Dockerfile. Set DATA_DIR to a persistent volume path. The binary is statically linked with no external dependencies.

docker build -t trough .
docker run -e FENCE_ADMIN_KEY=secret -v /data:/data -p 8790:8790 trough

When to use Stockyard instead

If you're building LLM-powered applications and need request tracing, cost tracking across 16 providers, model routing, prompt management, and team collaboration tools — Stockyard is the full platform. It includes capabilities from across the focused tools family in one binary.