DEVELOPER QUICKSTART

AI usage tracking API & integrations

Start with one project and one event. Add visibility where your workflow already runs.

ONE PROJECT. READ-ONLY CONTEXT.

Bring your signals into the conversation.

Both connections read your instrumented usage, automation health, and internal client-charge estimates. Create a dedicated project read key first. Provider API keys are not required.

Local Codex plugin

Download the local plugin

The download includes INSTALL.md. After extracting it, run npm ci --prefix server from that folder. The example below uses the full application source layout.

Use the included plugin/ source package. Install its server dependencies, then register the package with your Codex host’s supported local plugin workflow.

npm ci --prefix plugin/server

# In your MCP host's secure environment:
TRACEWELL_URL=https://tracewell.bhsoftwareproductions.com
TRACEWELL_READ_KEY=YOUR_PROJECT_READ_KEY

The package declares a local stdio server in plugin/mcp.json. Setup details are included in docs/PLUGIN.md. Source availability does not mean the plugin is installed in your host.

ChatGPT or a compatible MCP host

Add a custom MCP connection using the hosted endpoint and OAuth authentication. Review Tracewell’s consent page and authorize a dedicated project read key there; do not paste provider secrets or read keys into a chat.

Hosted MCP endpointhttps://tracewell.bhsoftwareproductions.com/mcp

Your host, account, and administrator must support custom MCP connections. The owner must configure the hosted OAuth origin and persistence. This page does not verify an installed connection.

Open the official ChatGPT setup guide

Only the metadata you send.

JavaScript SDK · Python SDK

These tools do not discover provider accounts, chat subscriptions, or every conversation. To connect a different project, use a separate dedicated read key and connection.

Create a project read key

Create a project

Open the workspace, choose Clients & projects, and give your work a name and monthly USD budget. Use real workspace mode only when authentication and the API are configured.

Open projects →

Issue a scoped key

Create an ingest key for that project. Copy its secret once and store it server-side. Never place it in browser code or send your provider credentials to Tracewell.

Send usage metadata

curl https://YOUR_HOST/api/v1/usage \
  -H 'Authorization: Bearer YOUR_PROJECT_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"eventId":"unique-event-id","provider":"custom",
       "model":"my-model","costUsd":0.042}'

Use a stable unique eventId to retry safely. Supply costUsd or both inputRatePerMillion and outputRatePerMillion with token counts. Without explicit pricing, cost remains unknown. Any provider or model name is supported.

Report outcomes

POST /api/v1/runs
{
  "eventId": "unique-run-id",
  "automationId": "YOUR_AUTOMATION_ID",
  "status": "success",
  "recordsProcessed": 12,
  "durationMs": 3400
}

Create an automation first. A missing run is evaluated after its expected interval plus five minutes. Failed or insufficient outcomes create in-app alerts. Alerts inform; they do not stop upstream workloads.

Bring context into Codex

Use the boxed connection quickstart above for the local Codex plugin or hosted OAuth MCP endpoint. Both expose project summaries, usage, automation outcomes, and internal client-charge estimates through dedicated project read access. Host setup and authorization are explicit.

It reads only the events you have instrumented. It does not discover chat subscriptions, inspect every Codex or ChatGPT conversation, or infer costs from account billing. To measure an API call, send its metadata through the ingest endpoint. Keep provider secrets separate from Tracewell keys.

Create a read-only project key →

Keep payloads lean

Only documented metadata fields are accepted. Prompts, completions, provider secrets, and arbitrary fields are rejected. JSON requests are limited to 16 KB. Event IDs are scoped by project and event type.