​
Public API

The AgentOps Public API provides read-only HTTP access to your monitoring data. This RESTful API allows you to retrieve trace information, span details, and metrics from any application or framework, regardless of programming language.
This is a read-only API for accessing existing data. To create traces and spans, use the AgentOps SDK or our instrumentation libraries.

​
Base URL

All API requests should be made to: 
https://api.agentops.ai

​
Authentication

The API uses JWT token authentication. You’ll need to exchange your API key for a JWT token first.

​
Get Access Token

Convert your API key to a bearer token for API access. 
curl -X POST https://api.agentops.ai/public/v1/auth/access_token \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY"
  }'
Important: Bearer tokens are valid for 30 days. Store them securely and refresh before expiration.

​
Core Endpoints

​
Get Project Information

Retrieve details about your current project. 
curl -X GET https://api.agentops.ai/public/v1/project \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN"
This endpoint returns information about the project associated with your API key.

​
Get Trace Details

Retrieve comprehensive information about a specific trace, including all its spans. 
curl -X GET https://api.agentops.ai/public/v1/traces/trace_123 \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN"
Parameters:
  • trace_id (path, required): The unique identifier of the trace
Response Fields:
  • trace_id: Unique trace identifier
  • project_id: Associated project ID
  • tags: Array of tags associated with the trace
  • spans: Array of span summaries within the trace

​
Get Trace Metrics

Retrieve aggregated metrics and statistics for a trace. 
curl -X GET https://api.agentops.ai/public/v1/traces/trace_123/metrics \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN"
Metrics Explained:
  • span_count: Total number of spans in the trace
  • success_count/fail_count/indeterminate_count: Status breakdown
  • *_tokens: Token usage breakdown by type
  • *_cost: Cost calculations in USD

​
Get Span Details

Retrieve comprehensive information about a specific span, including full attribute payloads. 
curl -X GET https://api.agentops.ai/public/v1/spans/span_456 \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN"
Parameters:
  • span_id (path, required): The unique identifier of the span
Response Fields:
  • attributes: Core span data (LLM calls, tool usage, etc.)
  • resource_attributes: Service and infrastructure metadata
  • span_attributes: Custom attributes set by your application

​
Get Span Metrics

Retrieve detailed metrics for a specific span. 
curl -X GET https://api.agentops.ai/public/v1/spans/span_456/metrics \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN"

​
MCP Server

AgentOps provides a Model Context Protocol (MCP) server that exposes the Public API as tools for AI assistants. This allows AI models to directly query your AgentOps data during conversations.

​
Configuration

Create an MCP server configuration file (typically mcp_config.json): Python-based configuration: 
{
  "mcpServers": {
    "agentops": {
      "command": "python",
      "args": ["-m", "agentops.mcp.server"],
      "env": {
        "AGENTOPS_API_KEY": "your-api-key-here"
      }
    }
  }
}
Docker-based configuration: 
{
  "mcpServers": {
    "agentops": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "AGENTOPS_API_KEY",
        "agentops/agentops-mcp:latest"
      ],
      "env": {
        "AGENTOPS_API_KEY": "your-agentops-api-key-here"
      }
    }
  }
}

​
Available Tools

The MCP server exposes the following tools that mirror the Public API endpoints:

​
auth

Authorize using an AgentOps project API key.
  • Parameters: api_key (string) - Your AgentOps project API key
  • Usage: The server will automatically prompt for authentication when needed

​
get_project

Get details about the current project.
  • Parameters: None
  • Returns: Project information including ID, name, and environment

​
get_trace

Get comprehensive trace information by ID.
  • Parameters: trace_id (string) - The trace identifier
  • Returns: Trace details with associated spans

​
get_trace_metrics

Get aggregated metrics for a specific trace.
  • Parameters: trace_id (string) - The trace identifier
  • Returns: Cost, token usage, and performance metrics

​
get_span

Get detailed span information by ID.
  • Parameters: span_id (string) - The span identifier
  • Returns: Complete span data including attributes

​
get_span_metrics

Get metrics for a specific span.
  • Parameters: span_id (string) - The span identifier
  • Returns: Span-specific cost and token metrics

​
Environment Variables

The MCP server supports the following environment variables:
  • AGENTOPS_API_KEY: Your AgentOps project API key
  • HOST: API endpoint (defaults to https://api.agentops.ai)