Phospho Documentation

Everything you need to integrate AI observability into your application.

Quick Start

Get up and running in under 5 minutes. You need an API key from your dashboard settings.

1Create an account

2Log your first event

Python

import requests

response = requests.post(
    "https://co-phospho-dak.nanocorp.app/api/v1/events",
    json={
        "input": "What is machine learning?",
        "output": "Machine learning is a branch of AI...",
    },
    headers={"Authorization": "Bearer ph_your_api_key"},
)
print(response.json())  # {"event_id": "...", "session_id": "..."}

3View it in the dashboard

Open your dashboard to see your event. That's it!

Python SDK

The Python SDK provides a simple interface for logging events from your Python applications.

Installation

Terminal

pip install phospho-sdk

Basic Usage

app.py

import phospho

# Initialize with your API key
phospho.init(api_key="ph_your_api_key")

# Log an LLM interaction
result = phospho.log(
    input="Summarize this document for me",
    output="Here is a summary of the key points...",
    session_id="conversation_123",  # optional
    user_id="user_456",             # optional
    metadata={                       # optional
        "model": "gpt-4",
        "tokens_in": 150,
        "tokens_out": 89,
        "latency_ms": 1230,
    },
)

print(result["event_id"])  # UUID of the logged event

Logging Feedback

app.py

# After getting user feedback:
phospho.feedback(
    event_id=result["event_id"],
    score=1,       # 1 = positive, 0 = negative
    comment="Great answer!",  # optional
)

JavaScript SDK

Use the JavaScript/TypeScript SDK for Node.js applications.

Installation

Terminal

npm install phospho-sdk

Usage

app.ts

import { Phospho } from "phospho-sdk";

const phospho = new Phospho({ apiKey: "ph_your_api_key" });

// Log an event
const result = await phospho.log({
  input: "What's the weather?",
  output: "It's sunny today!",
  sessionId: "sess_123",
  metadata: { model: "gpt-4", latencyMs: 800 },
});

// Log feedback
await phospho.feedback({
  eventId: result.eventId,
  score: 1,
});

REST API

You can also use the REST API directly. All endpoints require authentication via the Authorization: Bearer ph_xxx header.

Log an Event

POST /api/v1/events

curl -X POST https://co-phospho-dak.nanocorp.app/api/v1/events \
  -H "Authorization: Bearer ph_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "User question here",
    "output": "AI response here",
    "session_id": "optional_session_id",
    "user_id": "optional_user_id",
    "metadata": {
      "model": "gpt-4",
      "tokens_in": 100,
      "tokens_out": 50,
      "latency_ms": 1200
    }
  }'

Request Body

Field	Type	Required	Description
input	string	Yes	User input/prompt
output	string	Yes	AI response
session_id	string	No	Group events into sessions
user_id	string	No	Identify the user
metadata	object	No	Any additional data (model, tokens, latency, etc.)

Response

201 Created

{
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_id": "sess_abc123",
  "created_at": "2026-03-03T10:30:00Z"
}

User Feedback

Attach user feedback (thumbs up/down) to any event to track quality.

POST /api/v1/events/:event_id/feedback

curl -X POST https://co-phospho-dak.nanocorp.app/api/v1/events/EVENT_ID/feedback \
  -H "Authorization: Bearer ph_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"score": 1, "comment": "Great response!"}'

score	integer	Required	1 (positive) or 0 (negative)
comment	string	Optional	Free text feedback

Sessions

Group related events into sessions by passing a session_id when logging events. Sessions let you replay full conversations in the dashboard.

Python example

# All events with the same session_id are grouped together
session_id = "conv_" + str(uuid.uuid4())[:8]

phospho.log(input="Hello", output="Hi!", session_id=session_id)
phospho.log(input="What's 2+2?", output="4", session_id=session_id)
phospho.log(input="Thanks!", output="You're welcome!", session_id=session_id)

# View the full conversation in Dashboard > Sessions

Metadata

The metadata field is a flexible JSON object. You can pass any data you want, but these fields are automatically recognized by the dashboard:

Field	Type	Used For
model	string	Model identification
tokens_in	number	Token usage metrics
tokens_out	number	Token usage metrics
latency_ms	number	Latency chart in dashboard

Any additional fields you add will be visible in the event detail view.

Need help? Email us at support@phospho.app