Send the first trace

Use the SDK for normal integrations. Raw HTTP is the same contract underneath for non-Python agents and fixtures.

Install and configure

Run the service locally on Python 3.12+ with PROMPTETHEUS_API_KEY and optional PROMPTETHEUS_API_URL.

Install HTTP client

shellbash

pip install httpx

Local environment

.envbash

PROMPTETHEUS_API_URL="http://127.0.0.1:4318"
PROMPTETHEUS_API_KEY="pt_dev_key"

Emit with Python HTTP

Create a trace, then append schema-conformant events through the FastAPI ingestion gateway.

HTTP ingestion

agent.pypython

import os
import httpx

user_goal = "Book Tuesday at 2pm Pacific, but stop at confirmation"
api_url = os.environ.get("PROMPTETHEUS_API_URL", "http://127.0.0.1:4318")
headers = {
    "Authorization": f"Bearer {os.environ['PROMPTETHEUS_API_KEY']}",
    "Content-Type": "application/json",
}

with httpx.Client(base_url=api_url, headers=headers) as client:
    client.post(
        "/api/traces",
        json={
            "id": "trace_python_1",
            "agent": "browser-agent",
            "project_id": "proj_acmemeet",
            "user_goal": user_goal,
        },
    ).raise_for_status()

    client.post(
        "/api/traces/trace_python_1/events",
        json={
            "events": [
                {
                    "type": "user_message",
                    "session_id": "trace_python_1",
                    "timestamp": "2026-01-01T00:00:00Z",
                    "seq": 0,
                    "idempotency_key": "trace_python_1:dev:0",
                    "payload": {"content": user_goal},
                },
                {
                    "type": "goal_check",
                    "session_id": "trace_python_1",
                    "timestamp": "2026-01-01T00:00:01Z",
                    "seq": 1,
                    "idempotency_key": "trace_python_1:dev:1",
                    "payload": {
                        "passed": False,
                        "mismatches": ["Selected 2:00 AM instead of 2:00 PM"],
                    },
                },
            ]
        },
    ).raise_for_status()

Or post raw HTTP

Any stack can create a trace and POST schema-conformant events to the FastAPI endpoints.

Create trace

curlbash

curl -sS -X POST http://127.0.0.1:4318/api/traces \
  -H "Authorization: Bearer pt_dev_key" \
  -H "Content-Type: application/json" \
  -d '{"user_goal":"Book a room for Tuesday","agent":"demo-agent","id":"trace_curl_1"}'

Append event batch

curlbash

curl -sS -X POST http://127.0.0.1:4318/api/traces/trace_curl_1/events \
  -H "Authorization: Bearer pt_dev_key" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [{
      "type": "user_message",
      "session_id": "trace_curl_1",
      "timestamp": "2026-01-01T00:00:00Z",
      "seq": 0,
      "idempotency_key": "trace_curl_1:dev:0",
      "payload": {"content": "Book Tuesday"}
    }]
  }'

Single event envelope

event.jsonjson

{
  "type": "goal_check",
  "session_id": "trace_curl_1",
  "timestamp": "2026-01-01T00:00:01Z",
  "seq": 1,
  "idempotency_key": "trace_curl_1:dev:1",
  "payload": {
    "passed": false,
    "mismatches": ["Selected 2:00 AM instead of 2:00 PM"]
  }
}