Getting Started

1. Before you start

Create a free account

Sign up for a free Enprompta workspace. No credit card required — the Free plan includes 5,000 observability traces every month.

Create an API key

In the dashboard, open API Keys and create a key with the traces:write scope. You'll send it as a Bearer token in the next step.

Keep your API keys secure

Never expose API keys in client-side code or public repositories.

Recording traces works on every plan, including Free. Broader REST API access (prompts, executions, teams) requires a paid plan — see pricing.

Not a developer?

Sending traces means making a small change inside your app, where it calls the model — that's a job for an engineer. But you can do everything around it yourself and hand off just the snippet.

You can do now

Create the account & the traces:write key above
Watch traces appear in Observability once they're flowing

Hand to engineering

The Coding agent tab below — their AI agent (Claude Code, Cursor, …) wires it up end to end
Or the “Any OTel exporter” tab — a ~2-line env-var change for a team already on OpenTelemetry
Or the full tracing guide

2. Capture your first trace

New here? The easiest way is to let your coding agent do it — the first tab. On a Node or Python app it detects your stack, installs the SDK, wires everything up, and checks that a trace actually lands. Prefer to wire it yourself? The Enprompta SDK auto-instruments OpenAI, Anthropic & Gemini in one line, and anything else speaks standard OTLP/HTTP — cURL, the OpenTelemetry SDK, or any exporter you already run.

Get your first trace

Start with the first tab — let your coding agent set it up for you — or pick your stack and run the snippet yourself with your API key.

Any Skills-compatible agent — Claude Code, Cursor, Codex, …

# 1. Add the open Agent Skill to your agent (Claude Code, Cursor, Codex, …)
npx skills add enprompta/enprompta-skills --skill enprompta-instrumentation

# 2. Set your key — the agent references the env var, never the value
export ENPROMPTA_API_KEY=ep_your_api_key

# 3. Prompt your agent:
#    "Set up Enprompta tracing in my app."

The open Agent Skill teaches your agent to detect the stack, install the SDK, wire instrumentation, and verify a real trace lands — no manual coding. More in the tracing guide.

TypeScript — @enprompta/sdk

// npm install @enprompta/sdk
import { init } from '@enprompta/sdk'
import Anthropic from '@anthropic-ai/sdk'

// Pass the client you imported via `modules` (works under ESM & bundlers).
init({
  apiKey: process.env.ENPROMPTA_API_KEY,
  modules: { anthropic: Anthropic }, // also: { openai: OpenAI, google: GenerativeModel }
})

// Every call is now traced — no other code changes.
const anthropic = new Anthropic()
await anthropic.messages.create({
  model: 'claude-sonnet-4-6',
  max_tokens: 256,
  messages: [{ role: 'user', content: 'Hello' }],
})

Python — enprompta

# pip install enprompta
import enprompta

enprompta.auto_instrument(api_key="ep_your_api_key")

# Your existing OpenAI / Anthropic / Gemini calls are now traced:
from anthropic import Anthropic
client = Anthropic()
client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=256,
    messages=[{"role": "user", "content": "Hello"}],
)

OTLP/JSON via cURL

curl -X POST https://enprompta.com/api/ingest/otlp/v1/traces \
  -H "Authorization: Bearer ep_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceSpans": [{
      "scopeSpans": [{
        "spans": [{
          "traceId": "5b8efff798038103d269b633813fc60c",
          "spanId": "eee19b7ec3c1b174",
          "name": "chat",
          "startTimeUnixNano": "1700000000000000000",
          "endTimeUnixNano": "1700000001200000000",
          "status": { "code": 1 },
          "attributes": [
            { "key": "gen_ai.system", "value": { "stringValue": "openai" } },
            { "key": "gen_ai.request.model", "value": { "stringValue": "gpt-4o" } },
            { "key": "gen_ai.prompt", "value": { "stringValue": "Summarise this ticket." } },
            { "key": "gen_ai.completion", "value": { "stringValue": "The customer reports..." } },
            { "key": "gen_ai.usage.prompt_tokens", "value": { "intValue": 120 } },
            { "key": "gen_ai.usage.completion_tokens", "value": { "intValue": 48 } }
          ]
        }]
      }]
    }]
  }'

quickstart.py

import os
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

os.environ["OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"] = "https://enprompta.com/api/ingest/otlp/v1/traces"
os.environ["OTEL_EXPORTER_OTLP_TRACES_HEADERS"] = "Authorization=Bearer ep_your_api_key"

provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
trace.set_tracer_provider(provider)

tracer = trace.get_tracer("quickstart")
with tracer.start_as_current_span("chat") as span:
    span.set_attribute("gen_ai.system", "openai")
    span.set_attribute("gen_ai.request.model", "gpt-4o")
    span.set_attribute("gen_ai.prompt", "Summarise this ticket.")
    span.set_attribute("gen_ai.completion", "The customer reports...")
    span.set_attribute("gen_ai.usage.prompt_tokens", 120)
    span.set_attribute("gen_ai.usage.completion_tokens", 48)

provider.shutdown()  # flush the batch before the program exits

Environment variables

OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://enprompta.com/api/ingest/otlp/v1/traces"
OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Bearer ep_your_api_key"

Already running OpenTelemetry — directly or via OpenInference / OpenLLMetry auto-instrumentation? Set these two variables and your existing spans flow to Enprompta with no code changes.

Full SDK guides: TypeScript · Python.

A successful request returns 200. Spans are persisted asynchronously, so they appear a moment later.

See it land in your dashboard

Open Observability in the dashboard. Your chat span shows up with its model, prompt, completion, token counts — and cost and latency that Enprompta computes for you.

That's your first trace! 🎉

You now have live LLM observability. Everything else — prompt versioning, datasets, and evaluations — builds on the traces you just started collecting.

3. Where to go next

Traces are the doorway. From here, pick the path that matches what you're building.

Serve prompts at runtime

Fetch and render versioned prompts with the TypeScript or Python SDK — change a prompt without a redeploy.

Full tracing guide

Semantic conventions, linking prompts & sessions, OpenInference / OpenLLMetry auto-instrumentation, and quotas.

Run evaluations

Score traces and datasets with rule-based evaluators and the LLM-as-judge AI Grader.

Browse the REST API

Every endpoint, parameter, and response shape — prompts, executions, traces, teams, and webhooks.

4. Core concepts (API reference)

The reference below applies to every Enprompta REST endpoint — authentication, errors, rate limits, idempotency, and pagination. Reach for it when you move beyond tracing into the full API.

Authentication

The API supports two authentication methods: API Keys for server-to-server communication and OAuth2 Client Credentials for applications requiring scoped access.

API Keys (recommended)

Generate a key from your dashboard and include it in the Authorization header.

Request header

Authorization: Bearer ep_your_api_key_here

OAuth2 Client Credentials

For applications requiring scoped access, use the OAuth2 client credentials flow. Create a client in your dashboard under API Keys → OAuth Clients to get a client_id and client_secret (the secret is shown once).

Token request

curl -X POST https://enprompta.com/api/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "scope": "prompts:read prompts:write"
  }'

Available OAuth2 scopes:

prompts:readprompts:writeexecutions:readexecutions:writeteams:readteams:writewebhooks:manageanalytics:read

Error handling

All API errors follow a consistent format with numeric error codes for easy handling.

Error response format

{
  "success": false,
  "error": {
    "code": 1001,
    "type": "AUTH_INVALID_TOKEN",
    "message": "The provided API key is invalid or expired",
    "request_id": "req_abc123xyz"
  }
}

Error code ranges

Range	Category	Description
`1xxx`	Authentication	Invalid tokens, expired keys, missing credentials
`2xxx`	Validation	Invalid input, schema errors, missing fields
`3xxx`	Resource	Not found, already exists, conflicts
`4xxx`	Rate Limiting	Rate limit exceeded, quota exhausted
`5xxx`	Server	Internal errors, service unavailable

Rate limits

Rate limits are applied per API key and vary by the key's rate-limit tier.

Tier	Requests/min	Requests/day
Free	— (trace ingestion only)	—
Pro (standard key)	60	10,000
Pro (premium key)	300	100,000
Enterprise	Custom (up to 1,000+)	Custom

Rate limit headers are included in every response:

Response headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1705312800

Idempotency

For safe retries on POST, PUT, and PATCH requests, include an Idempotency-Key header.

Idempotent request

curl -X POST https://enprompta.com/api/v1/prompts \
  -H "Authorization: Bearer ep_your_api_key" \
  -H "Idempotency-Key: unique-request-id-12345" \
  -H "Content-Type: application/json" \
  -d '{"title": "My Prompt", "content": "Hello {{name}}"}'

Keys must be 1-255 alphanumeric characters (underscores and hyphens allowed)
Duplicate requests with the same key return the cached response
Keys expire after 24 hours
The response includes X-Idempotent-Replayed: true if cached

Pagination

List endpoints use cursor-based pagination for efficient traversal of large datasets.

Paginated request

# First page
curl "https://enprompta.com/api/v1/prompts?limit=20"

# Next page using cursor
curl "https://enprompta.com/api/v1/prompts?limit=20&cursor=eyJpZCI6IjEyMyJ9"

Pagination response

{
  "success": true,
  "data": [...],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJpZCI6IjEyMyIsInNvcnQiOiIyMDI0LTAxLTE1In0",
    "previous_cursor": null,
    "total_count": 150,
    "limit": 20
  }
}

What you'll end up with

On this page