Send your first trace with REST and cURL

Try the HTTP API before adding an SDK. Generate a current request, send it, and optionally query batch status.

Before you start

A POSIX shell (macOS, Linux or WSL), Python 3 and cURL, plus a project API key.

Keep project API keys out of browser code, screenshots and source control. No model API key is required for this test.

1. Create a project and API key

Create a free account, verify your email, then create or select a project in Project management. Open API keys for that project, create a key and complete email verification. Save the key when it is displayed.

2. Set your environment

# macOS / Linux / WSL
export METERTRAIL_ENDPOINT="https://metertrail.com"
printf 'Project API key (input is visible): '
IFS= read -r METERTRAIL_API_KEY
export METERTRAIL_API_KEY

# Windows PowerShell (Node.js / Python tutorials)
$env:METERTRAIL_ENDPOINT = "https://metertrail.com"
$env:METERTRAIL_API_KEY = Read-Host "Project API key" -MaskInput

3. Send a sample trace

Save as send.sh and run from the same terminal where you set the environment variables.

#!/usr/bin/env sh
set -eu
: "${METERTRAIL_API_KEY:?Set your project API key}"
: "${METERTRAIL_ENDPOINT:?Set endpoint}"
python3 - <<'PY' > batch.json
import json, uuid
from datetime import datetime, timezone
print(json.dumps({
    "schemaVersion": "1.0",
    "agent": {"serviceName": "rest-example", "environment": "development", "instanceId": str(uuid.uuid4())},
    "events": [{"eventId": str(uuid.uuid4()), "objectId": str(uuid.uuid4()),
                "type": "trace", "revision": 1, "traceId": uuid.uuid4().hex,
                "startedAt": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
                "data": {"name": "Example request", "status": "success", "durationMs": 120}}]
}))
PY
curl --fail-with-body --max-time 10 "$METERTRAIL_ENDPOINT/v1/events/batch" \
  -H "Authorization: Bearer $METERTRAIL_API_KEY" \
  -H 'Content-Type: application/json' --data @batch.json

sh send.sh

Each run generates one new event and can consume one monitoring unit. For a network retry, resend the same batch.json unchanged instead of generating new IDs. This is a sample trace, not a real model request.

4. Check the result

A successful upload returns HTTP 200. pending is a receipt for asynchronous processing, not a confirmation that data is already queryable.

{"batchId":"<batch-id>","received":1,"status":"pending"}

Optionally query the returned batchId using the same project key:

curl --fail-with-body --max-time 10 "https://metertrail.com/v1/batches/<batch-id>" \
  -H "Authorization: Bearer $METERTRAIL_API_KEY"

5. Find the trace in your console

Select the project associated with your key and open Traces. Refresh after processing and find Example request. Model cost can be Unknown because this minimal example does not report model usage or prices.

Troubleshooting

401: check the key and project. 400: check required fields and timestamps. For quota or subscription errors, check Billing. After a network timeout retry the same event IDs and content rather than creating new objects.

Other tutorials: