Skip to main content

​
Quickstart: fire your first event in under a minute

You don’t need to set anything up first. When you fire an event with a new customerExternalId, agentCode, or signalName, MarginFront creates the customer, agent, or signal automatically. Your existing user IDs from your own database flow straight through. The dashboard updates the moment the event lands.
This guide takes you from zero to a real usage event visible in the dashboard. The first three steps are all you need for cost tracking. Step 4 is optional for revenue tracking and invoicing. We use plain curl so the examples work regardless of language. The Node SDK and MCP versions are at the bottom.

​
1. Get an API key

In the MarginFront dashboard, go to Developer Zone → API Keys. Copy a secret key (looks like mf_sk_test_...) or create a new one. Export it: 
export MF_API_SECRET_KEY="mf_sk_test_..."
The API key alone identifies your organization. You don’t need to pass an org ID anywhere. The production API base URL is https://api.marginfront.com. All examples below use it.

​
2. Fire your first usage event

This is the only call you need to integrate MarginFront. Three of the fields use IDs from your own system. MarginFront creates the customer, agent, and signal on the spot if they don’t exist yet. 
curl -X POST https://api.marginfront.com/v1/usage/record \
  -H "x-api-key: $MF_API_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {
        "customerExternalId": "<your_db_user_id>",
        "agentCode": "<your_agent_identifier>",
        "signalName": "<the_thing_that_happened>",
        "model": "gpt-4o",
        "modelProvider": "openai",
        "inputTokens": 523,
        "outputTokens": 117
      }
    ]
  }'
Field semantics:
  • customerExternalId is whatever ID your system already uses for this user (e.g. usr_abc123).
  • agentCode is a stable name for the agent doing the work (e.g. report_writer).
  • signalName is what the agent did (e.g. report_generated).
  • model and modelProvider are required so MarginFront can look up that model’s input and output token rates.
What models does MarginFront recognize? The catalog has 1100+ entries across LLM and non-LLM services (Cloud Run, Twilio, Google Places, etc.). To discover the canonical name for your service, list the catalog: GET /v1/services?provider=<your-provider>. See the Services Catalog reference for the full endpoint and the Supported Services overview for what’s covered. If your service is in the catalog, fire events with the canonical name and cost auto-resolves on ingest. If not, the event still lands but cost stays null until the catalog is updated.
The endpoint references the customer and agent by their string IDs, not their UUIDs. What you should see: 
{
  "processed": 1,
  "successful": 1,
  "failed": 0,
  "results": {
    "success": [
      {
        "customerExternalId": "<your_db_user_id>",
        "agentCode": "<your_agent_identifier>",
        "signalName": "<the_thing_that_happened>",
        "model": "gpt-4o",
        "modelProvider": "openai",
        "totalCostUsd": "0.0024780000",
        "eventId": "8a7b6c5d-...",
        "rawEventId": "f1e2d3c4-...",
        "timestamp": "2026-04-27T..."
      }
    ],
    "failed": []
  }
}
If the response is successful: 1, you just logged a real event and three records were created behind the scenes for you.

​
3. Look at the dashboard

Log into app.marginfront.com and open the Home page. You should see one event with the customer, agent, signal, model, and calculated cost. The customer, agent, and signal you sent are now real records in your dashboard. You can also fetch the same data via the API: 
curl "https://api.marginfront.com/v1/analytics/usage?startDate=2026-04-01&endDate=2026-04-30" \
  -H "x-api-key: $MF_API_SECRET_KEY"

​
What just got created

When the event landed, MarginFront did three things automatically:
  • Customer. Created from the customerExternalId you sent. The display name defaults to the same string, so you may see usr_abc123 in the customer column at first. Rename it later in the dashboard or via the customers API.
  • Agent. Created from the agentCode. Display name defaults to the same string.
  • Signal. Created from the signalName. Display name defaults to the same string.
That is the full setup for cost tracking. Every future event with the same customerExternalId rolls up under that customer. Same for agents and signals. What does not auto-create:
  • Pricing plans and subscriptions (Step 4 below, optional).
  • Invoices.
  • Team members.

​
4. Add revenue tracking (optional)

Skip this step if you only need cost tracking. Without a pricing plan, MarginFront still tracks costs. It just won’t generate revenue numbers or invoices. To track revenue, you need two things:
  1. A pricing plan that defines per-unit charges.
  2. A subscription that ties one of your customers to that plan.
Both can be created in the dashboard (easier) or via the API. Full reference: pricing plans, pricing strategies, subscriptions. Once a customer has an active subscription, every event fires both a cost calculation and a revenue calculation. Invoices follow on the billing cycle you configure.

​
Same thing, using the Node SDK

If your app is Node.js, install the SDK: 
npm install @marginfront/sdk

import { MarginFrontClient } from "@marginfront/sdk";

const mf = new MarginFrontClient(process.env.MF_API_SECRET_KEY);

await mf.usage.record({
  customerExternalId: "<your_db_user_id>", // whatever ID your system already uses for this user
  agentCode: "<your_agent_identifier>", // a stable name for this agent. e.g. "report_writer"
  signalName: "<the_thing_that_happened>", // what the agent did. e.g. "report_generated"
  model: "gpt-4o",
  modelProvider: "openai",
  inputTokens: 523,
  outputTokens: 117,
});
Same auto-provision behavior. By default the SDK runs in fire-and-forget mode: if MarginFront is unreachable, events buffer locally and retry. Your agent never stalls.

​
Same thing, using MCP

MCP lets you ask Claude, Gemini, or ChatGPT to operate on your MarginFront account in plain English. Use it for backfills, batch operations, queries, and admin actions. MCP is not how you instrument your product. For per-event tracking from your own code, use the curl or SDK examples above. To connect MCP, add this to .mcp.json in your project root: 
{
  "mcpServers": {
    "marginfront": {
      "command": "npx",
      "args": ["-y", "@marginfront/mcp"],
      "env": {
        "MF_API_SECRET_KEY": "mf_sk_test_..."
      }
    }
  }
}
Then ask your AI: "Show me MarginFront usage analytics for today" or "Find the customer with external ID usr_abc123". See MCP Setup Guide for the full tool list.

​
You’re done

You just shipped a working integration. Suggested next steps:
  • Wire this into real code. Call /v1/usage/record (or mf.usage.record(...)) from your product code every time work happens.
  • Batch high-volume traffic. The endpoint accepts up to 100 records per call.
  • Track multi-service events. When one outcome uses several services (search + LLM + email, for example), pass a services[] array on the request body. See the SDK tracking-events guide, Example 5.
  • Add revenue tracking. When you’re ready to bill, follow Step 4 above.
  • Read the usage-events reference. Full field list and what happens when a model isn’t recognized.

​
Help, something didn’t work

Cross-reference the response body with errors.md. Still stuck? Email [email protected] with:
  • The curl command (API key REDACTED, never share it).
  • The full response body you got back.
We’ll get you unstuck.

​
Where else to look