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. Every curl example on this page comes in two versions: Bash (macOS, Linux, WSL, Git Bash) and PowerShell (Windows). Pick the tab that matches your terminal. The two are not interchangeable, and copying the Bash version into PowerShell is the most common cause of a 401 with a perfectly good key. Commands that are identical in both shells, like npm install, appear once.

1. Get an API key

In the MarginFront dashboard, go to Build → API keys and create a key pair (or use a secret key you already saved). Copy the secret key (looks like mf_sk_test_...) the moment it’s shown — you can’t see the full value again after the first time. Put it in an environment variable:

export MF_API_SECRET_KEY="mf_sk_your_key_here"

$env:MF_API_SECRET_KEY = "mf_sk_your_key_here"

Windows: the $env: prefix is not optional. PowerShell reads $MF_API_SECRET_KEY as a variable it has never heard of, substitutes an empty string, and sends a request with no key. The API answers 401, which reads like a bad key even though the key is fine. Write $env:MF_API_SECRET_KEY every time you reference it.

The variable lives only in the terminal window you set it in. Open a new window and you set it again. To make it permanent on Windows, use System Properties → Environment Variables, or run setx MF_API_SECRET_KEY "mf_sk_your_key_here" once and open a new terminal. 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.

You invent these three IDs. Nothing has to exist in MarginFront first. test_user_001, report_writer, and report_generated below are values made up for this example. Send whatever strings you like, as long as you keep using the same ones for the same customer, agent, and signal. The records get created on the first event that mentions them.

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": "test_user_001",
        "agentCode": "report_writer",
        "signalName": "report_generated",
        "model": "gpt-4o",
        "modelProvider": "openai",
        "inputTokens": 523,
        "outputTokens": 117
      }
    ]
  }'

$body = @'
{
  "records": [
    {
      "customerExternalId": "test_user_001",
      "agentCode": "report_writer",
      "signalName": "report_generated",
      "model": "gpt-4o",
      "modelProvider": "openai",
      "inputTokens": 523,
      "outputTokens": 117
    }
  ]
}
'@

$body | curl.exe -X POST https://api.marginfront.com/v1/usage/record `
  -H "x-api-key: $env:MF_API_SECRET_KEY" `
  -H "Content-Type: application/json" `
  -d '@-'

Windows: three more things that bite.

Use curl.exe, not curl. In Windows PowerShell, curl is an alias for Invoke-WebRequest, a different command whose parameters do not match curl’s. It fails with a parameter error. Spelling out curl.exe runs the real curl that ships with Windows 10 and later.

Put the JSON in a here-string. The @' and '@ markers quote the block literally. The closing '@ has to sit at the very start of its own line or PowerShell will not end the string.

Pipe the body in rather than passing it as an argument. $body | ... -d '@-' hands the JSON to curl on standard input, and '@-' is curl’s name for standard input. Writing -d $body instead breaks on Windows PowerShell 5.1 and on PowerShell 7.0 through 7.2. Those versions strip the double quotes out of any argument containing spaces, so curl receives {records: [...]} and the API rejects it. Piping avoids that entirely and works on every version.

Field semantics:

customerExternalId is your own ID for this user. In real code that’s the ID your database already uses (e.g. usr_abc123). For a first test, any string works.
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": "test_user_001",
        "agentCode": "report_writer",
        "signalName": "report_generated",
        "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"

curl.exe "https://api.marginfront.com/v1/analytics/usage?startDate=2026-04-01&endDate=2026-04-30" `
  -H "x-api-key: $env:MF_API_SECRET_KEY"

Keep the quotes around the URL in PowerShell. & is reserved there. Unquoted, Windows PowerShell 5.1 refuses the line outright (“The ampersand (&) character is not allowed”), while PowerShell 7 cuts the command at the &, runs the truncated URL as a background job, and errors on the leftover text.

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 test_user_001 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:

A pricing plan that defines per-unit charges.
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: "test_user_001", // your own ID for this user. any stable string works
  agentCode: "report_writer", // a stable name for this agent
  signalName: "report_generated", // what the agent did
  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_your_key_here"
      }
    }
  }
}

Then ask your AI: "Show me MarginFront usage analytics for today" or "Find the customer with external ID test_user_001". 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

Got a 401 on Windows with a key you know is good? Check these three in order. Each one sends an empty or malformed key and produces the same 401.

You wrote $MF_API_SECRET_KEY instead of $env:MF_API_SECRET_KEY.
You ran curl instead of curl.exe, so PowerShell used Invoke-WebRequest.
You set the variable in a different terminal window than the one you are calling from.

To confirm the variable is set in this window without printing the key itself, run $env:MF_API_SECRET_KEY.Length. A number means it’s set. A blank line or an error means it isn’t, and the request went out with no key. 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

Discover canonical model names: Services Catalog | Supported Services overview
Full page index: https://docs.marginfront.com/sitemap.xml
LLM-friendly reference: https://docs.marginfront.com/llms.txt
MCP-specific reference (for AI assistants connecting via MCP): https://marginfront.com/llms-mcp.txt

Getting Started

SDK Guide

MCP Guide

Integration Recipes

Internal Code Cost Clarity

Quickstart

Quickstart: fire your first event in under a minute

1. Get an API key

2. Fire your first usage event

3. Look at the dashboard

What just got created

4. Add revenue tracking (optional)

Same thing, using the Node SDK

Same thing, using MCP

You’re done

Help, something didn’t work

Where else to look

​Quickstart: fire your first event in under a minute

​1. Get an API key

​2. Fire your first usage event

​3. Look at the dashboard

​What just got created

​4. Add revenue tracking (optional)

​Same thing, using the Node SDK

​Same thing, using MCP

​You’re done

​Help, something didn’t work

​Where else to look

Quickstart: fire your first event in under a minute

1. Get an API key

2. Fire your first usage event

3. Look at the dashboard

What just got created

4. Add revenue tracking (optional)

Same thing, using the Node SDK

Same thing, using MCP

You’re done

Help, something didn’t work

Where else to look