Get started with Track

On this page

This is the tutorial. Follow it in order and you will have events in your dashboard in about five minutes. If you already have events and need a field, route or limit, use the reference guide instead.

Track shows which AI agents call your API, which paths convert, and which journeys pay. You do not need an account or a card: your coding agent creates a free workspace and hands you a claim link.

What you need

  • An API in a git repository (Express, Fastify, FastAPI or Starlette have a ready install)
  • Claude Code, Cursor, Codex, or another coding agent
  • About five minutes

The one-prompt install covers Node with Express or Fastify, and Python with FastAPI or Starlette. On another framework the agent writes the part that sends events itself, from the same reference, and every other step is the same; or read Send your first events and do it by hand.

Step 1. Paste this into your coding agent

Open your API repository in Claude Code, Cursor, or Codex and paste this:

prompt
Read https://alg.katrinalaszlo.com/SKILL.md and follow it to install Track in this API.

Find the field in this codebase that identifies the customer (the user, org, or key id your
auth resolves) and use it as the account id. Ask me only if it is genuinely ambiguous.

Add Track the way the skill says for this framework, send a few test requests, and run the
install check until it says RESULT: PASS. Do not print or commit the key or salt. Finish by
showing me the claim link.

Step 2. Let it install

The agent will do four things:

1. Create a free workspace with no email, account form, or card. 2. Add @katrinalaszlo/track and two lines of middleware in this repository. 3. Read your auth code to find the customer id and send a few test requests. 4. Run the install check and give you a claim link.

The key and salt go into .env. The agent must not print them or commit them.

Step 3. Confirm it worked

The install is done when the check ends in this line:

text
RESULT: PASS

The check fails when events, sessions, status codes or account ids are missing. Read the PASS and FAIL lines, fix the first FAIL, and run it again.

Step 4. Claim the workspace

Open the claim link the agent gave you. Sign in, choose Add to my account, and the workspace, its projects, and everything the agent did are yours.

The link works for seven days. The key keeps working after the claim, and an unclaimed workspace is not deleted.

Step 5. Read your first report

Open the demo reports or your dashboard. Start with three questions:

  • Who called the API: known agents, declared agents, automation, humans or unknown?
  • Where did sessions end: which paths reached signup, a key and a payment?
  • Which journeys paid, and which agent did the work?

If something fails

Track errors are JSON with an HTTP status and a next action:

json
{
  "error": "invalid_key",
  "message": "The API key is missing or not valid for this project.",
  "next_step": "Send the key from .env as Authorization: Bearer.",
  "resolved_by": "agent"
}

Give the next_step to your coding agent. resolved_by says whether the agent can fix it or a person has to decide. The CLI prints the same guidance when it can.

Common first failures:

  • No events: the server was not restarted after app.use(...), or the request never reached the server.
  • 401 or 403: the key is missing, revoked, or for another project.
  • Events rejected: read the rejection reason in the response or on the Install page and fix that field.
  • A person is needed: checkout, KYC or an approval step is outside the agent's path. Record it as a handoff.

Next