Skip to content

API Reference

Jump to bottom
mohit-nagaraj edited this page Jan 13, 2026 · 2 revisions

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)
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"

# 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 Computed: (input_count - output_count) / input_count
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

Clone this wiki locally