API Reference

Complete endpoint documentation for the X-Ray Logger API.

Base URL: http://localhost:8000

---

Authentication

All endpoints (except /health) require API key authentication if XRAY_API_KEY is set on the server.

Header: Authorization: Bearer <your-api-key>

---

Endpoints

Health Check

GET /health

Health check endpoint to verify API availability.

Request: No parameters

Response:

{
  "status": "healthy"
}

Example:

curl http://localhost:8000/health

---

Ingest Events

POST /ingest

Ingest batched pipeline events from the SDK. This is the primary endpoint used by the SDK to send observability data.

Authentication: Required (if enabled)

Request Body:

[
  {
    "id": "event-uuid",
    "event_type": "run_start",
    "run_id": "run-uuid",
    "pipeline_name": "my-pipeline",
    "started_at": "2024-01-15T10:30:00Z",
    "input_summary": { ... },
    "metadata": { ... }
  },
  {
    "id": "event-uuid",
    "event_type": "step_start",
    "step_id": "step-uuid",
    "run_id": "run-uuid",
    "step_name": "filter_products",
    "step_type": "filter",
    "index": 0,
    "started_at": "2024-01-15T10:30:01Z"
  }
]

Event Types:

• run_start - Pipeline execution started
• run_end - Pipeline execution completed
• step_start - Step execution started
• step_end - Step execution completed

Response:

{
  "processed": 2,
  "succeeded": 2,
  "failed": 0,
  "results": [
    {
      "id": "event-uuid",
      "event_type": "run_start",
      "success": true
    }
  ]
}

Example:

curl -X POST http://localhost:8000/ingest \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '[{"event_type": "run_start", ...}]'

---

List Runs

GET /xray/runs

List pipeline runs with optional filters and pagination.

Authentication: Required (if enabled)

Query Parameters:

Parameter	Type	Required	Default	Description
pipeline	string	No	-	Filter by pipeline name
status	string	No	-	Filter by status (running, success, error)
user_id	string	No	-	Filter by user ID
request_id	string	No	-	Filter by request ID
environment	string	No	-	Filter by environment
limit	integer	No	100	Max results (1-1000)
offset	integer	No	0	Results to skip

Response:

{
  "runs": [
    {
      "id": "run-uuid",
      "pipeline_name": "product-recommendations",
      "status": "success",
      "started_at": "2024-01-15T10:30:00Z",
      "ended_at": "2024-01-15T10:30:05Z",
      "input_summary": { ... },
      "output_summary": { ... },
      "metadata": { ... },
      "request_id": "req-123",
      "user_id": "user-456",
      "environment": "production",
      "error_message": null
    }
  ],
  "total": 150,
  "limit": 100,
  "offset": 0
}

Example:

# List all runs
curl http://localhost:8000/xray/runs

# Filter by pipeline
curl "http://localhost:8000/xray/runs?pipeline=product-recommendations"

# Filter by status and user
curl "http://localhost:8000/xray/runs?status=success&user_id=user-123"

# Pagination
curl "http://localhost:8000/xray/runs?limit=50&offset=100"

---

Get Run

GET /xray/runs/{run_id}

Get a single run by ID with all its steps.

Authentication: Required (if enabled)

Path Parameters:

• run_id (UUID, required) - The run ID

Response:

{
  "id": "run-uuid",
  "pipeline_name": "product-recommendations",
  "status": "success",
  "started_at": "2024-01-15T10:30:00Z",
  "ended_at": "2024-01-15T10:30:05Z",
  "input_summary": { ... },
  "output_summary": { ... },
  "metadata": { ... },
  "request_id": "req-123",
  "user_id": "user-456",
  "environment": "production",
  "error_message": null,
  "steps": [
    {
      "id": "step-uuid",
      "run_id": "run-uuid",
      "step_name": "filter_products",
      "step_type": "filter",
      "index": 0,
      "started_at": "2024-01-15T10:30:01Z",
      "ended_at": "2024-01-15T10:30:02Z",
      "duration_ms": 1000,
      "input_summary": { ... },
      "output_summary": { ... },
      "input_count": 100,
      "output_count": 50,
      "removed_ratio": 0.5,
      "reasoning": { ... },
      "metadata": { ... },
      "status": "success",
      "error_message": null
    }
  ]
}

Example:

curl http://localhost:8000/xray/runs/550e8400-e29b-41d4-a716-446655440000

---

List Steps

GET /xray/steps

List pipeline steps with optional filters and pagination.

Authentication: Required (if enabled)

Query Parameters:

Parameter	Type	Required	Default	Description
run_id	UUID	No	-	Filter by parent run ID
step_type	string	No	-	Filter by step type (filter, rank, llm, etc.)
step_name	string	No	-	Filter by step name
status	string	No	-	Filter by status (running, success, error)
min_removed_ratio	float	No	-	Filter steps with removed_ratio >= value (0.0-1.0)
limit	integer	No	100	Max results (1-1000)
offset	integer	No	0	Results to skip

Response:

{
  "steps": [
    {
      "id": "step-uuid",
      "run_id": "run-uuid",
      "step_name": "filter_products",
      "step_type": "filter",
      "index": 0,
      "started_at": "2024-01-15T10:30:01Z",
      "ended_at": "2024-01-15T10:30:02Z",
      "duration_ms": 1000,
      "input_summary": { ... },
      "output_summary": { ... },
      "input_count": 100,
      "output_count": 50,
      "removed_ratio": 0.5,
      "reasoning": { ... },
      "metadata": { ... },
      "status": "success",
      "error_message": null
    }
  ],
  "total": 500,
  "limit": 100,
  "offset": 0
}

Example:

# List all steps
curl http://localhost:8000/xray/steps

# Filter by step type
curl "http://localhost:8000/xray/steps?step_type=filter"

# Filter by run
curl "http://localhost:8000/xray/steps?run_id=550e8400-e29b-41d4-a716-446655440000"

# Find steps that removed ≥10% of items (useful for analyzing filter effectiveness)
curl "http://localhost:8000/xray/steps?min_removed_ratio=0.1"

# Combine filters: filter steps that removed ≥50% of items
curl "http://localhost:8000/xray/steps?step_type=filter&min_removed_ratio=0.5"

# Cross-pipeline analysis
curl "http://localhost:8000/xray/steps?step_type=llm&limit=1000"

---

Data Models

Run

Field	Type	Description
id	UUID	Unique run identifier
pipeline_name	string	Pipeline name (e.g., "product-recommendations")
status	string	running, success, or error
started_at	datetime	When the run started (ISO 8601)
ended_at	datetime	When the run completed (ISO 8601, nullable)
input_summary	object	Summarized input data
output_summary	object	Summarized output data
metadata	object	Additional metadata (request_id, user_id, etc.)
request_id	string	Request identifier (nullable)
user_id	string	User identifier (nullable)
environment	string	Environment (e.g., "production", "staging")
error_message	string	Error details if status is "error" (nullable)

Step

Field	Type	Description
id	UUID	Unique step identifier
run_id	UUID	Parent run ID
step_name	string	Step name (e.g., "filter_products")
step_type	string	Step type (filter, rank, llm, retrieval, transform)
index	integer	Order within the run (0-based)
started_at	datetime	When the step started (ISO 8601)
ended_at	datetime	When the step completed (ISO 8601, nullable)
duration_ms	integer	Execution time in milliseconds (nullable)
input_summary	object	Summarized input data
output_summary	object	Summarized output data
input_count	integer	Number of input items (nullable)
output_count	integer	Number of output items (nullable)
removed_ratio	float	Stored: (input_count - output_count) / input_count (indexed for fast filtering)
reasoning	object	Decision reasoning and metadata
metadata	object	Additional step-specific metadata
status	string	running, success, or error (nullable)
error_message	string	Error details if status is "error" (nullable)

---

Error Responses

All endpoints return standard HTTP status codes:

Status Code	Description
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Missing or invalid API key
404	Not Found - Resource doesn't exist
422	Unprocessable Entity - Validation error
500	Internal Server Error

Error Response Format:

{
  "detail": "Error message description"
}

---

Rate Limits

Currently no rate limits are enforced. The API is designed for internal observability use.

---

SDK Usage

Most users interact with the API through the SDK rather than directly:

from xray_logger import init_xray, step

client = init_xray(base_url="http://localhost:8000")

@step(step_type="filter")
def my_step(items):
    # SDK automatically calls /ingest
    return filtered_items

with client.start_run("my-pipeline"):
    result = my_step(items)

See Quick Start for SDK usage examples.

---

Additional Resources

• Architecture - System architecture and data flow
• Quick Start - Getting started guide
• GitHub Repository