API Documentation - Mesh-Trace

Authentication #

All API requests require a valid API key passed via the Authorization header using Bearer token authentication.

Bearer Token

Include your API key in every request header. Keys prefixed with mtk_test_ access sandbox data only.

HTTP Header

Authorization: Bearer mtk_live_a1b2c3d4e5f6...

Generate API keys from Settings > API Keys in the dashboard. Each key is scoped to your organization and can be revoked at any time.

API keys carry the same permissions as your user account. Store them securely and never expose them in client-side code or version control.

Base URL #

All API requests should be sent to the following base URL.

Base URL

https://api.cloud-tracing-mesh.net/v1

For enterprise customers with dedicated infrastructure, your base URL may differ. Check your onboarding email or contact your account manager.

Rate Limits #

The API uses a sliding window rate limiter scoped per API key.

1,000 requests per minute

Rate limit headers are included in every response so you can track your usage:

                Response Headers
                
              
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 997
X-RateLimit-Reset: 1710504000

When rate limited, the API returns 429 Too Many Requests. Implement exponential backoff in your integration. Enterprise plans support custom rate limits up to 10,000 req/min.

Error Handling #

The API uses conventional HTTP status codes to indicate success or failure. Error responses include a structured JSON body.

              Error Response
              
            
{
  "error": {
    "code": "invalid_parameter",
    "message": "Parameter 'start_time' must be a valid ISO 8601 timestamp",
    "param": "start_time",
    "request_id": "req_7f3a8b2e4d"
  }
}

Status	Meaning	Common Causes
200	OK	Request succeeded
201	Created	Resource created successfully
400	Bad Request	Invalid parameters or malformed JSON
401	Unauthorized	Missing or invalid API key
403	Forbidden	API key lacks required permissions
404	Not Found	Resource does not exist
429	Rate Limited	Too many requests — back off and retry
500	Server Error	Internal error — contact support if persistent
503	Unavailable	Service temporarily unavailable

SDKs & Libraries #

Official client libraries with full type definitions, automatic retries, and built-in pagination support.

PY

Python

pip install mesh-trace

JS

Node.js / TypeScript

npm i @mesh-trace/sdk

Go

go get mesh-trace/sdk-go

RB

Ruby

gem install mesh_trace

Python — Quick Example

from mesh_trace import Client

client = Client(api_key="mtk_live_a1b2c3...")

# List recent traces for a service
traces = client.traces.list(
    service="api-gateway",
    min_duration_ms=100,
    limit=20
)

for trace in traces:
    print(f"{trace.trace_id} — {trace.duration_ms}ms")

Traces #

Query and search distributed traces captured by Mesh-Trace collectors across your infrastructure.

GET /v1/traces List recent traces

Query Parameters

Parameter	Type	Description
`service`	string	Filter by service name (e.g. `api-gateway`)
`start_time`	ISO 8601	Start of the query window. Default: 1 hour ago
`end_time`	ISO 8601	End of the query window. Default: now
`min_duration_ms`	integer	Minimum trace duration in milliseconds
`status`	string	Filter by status: `ok`, `error`, `unset`
`limit`	integer	Max results (1–200). Default: 50
`cursor`	string	Pagination cursor from previous response

Example Response

                  JSON
                  
                
{
  "traces": [
    {
      "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
      "root_service": "api-gateway",
      "root_operation": "POST /api/orders",
      "duration_ms": 142,
      "span_count": 23,
      "status": "ok",
      "started_at": "2026-03-15T08:22:41.003Z",
      "services": ["api-gateway", "order-svc", "inventory-svc", "payment-svc"]
    }
  ],
  "next_cursor": "eyJsYXN0X3RzIjoiMjAyNi0wMy0xNVQwODoyMjo0MC4wMDBaIn0=",
  "total_matched": 1847
}

GET /v1/traces/{trace_id} Get full trace with all spans

Path Parameters

Parameter	Type	Description
`trace_id` required	string	32-character hex trace ID (W3C format)

Example Response

                  JSON
                  
                
{
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "duration_ms": 142,
  "span_count": 23,
  "spans": [
    {
      "span_id": "00f067aa0ba902b7",
      "parent_span_id": null,
      "operation_name": "POST /api/orders",
      "service_name": "api-gateway",
      "duration_ms": 142,
      "status_code": "OK",
      "attributes": {
        "http.method": "POST",
        "http.url": "/api/orders",
        "http.status_code": 201,
        "net.peer.name": "order-svc.default.svc.cluster.local"
      },
      "started_at": "2026-03-15T08:22:41.003Z",
      "events": []
    }
  ]
}

POST /v1/traces/search Advanced trace search

Request Body

Field	Type	Description
`query` required	string	Search expression (e.g. `service.name = "api-gateway" AND duration > 100ms`)
`start_time` required	ISO 8601	Start of the search window
`end_time` required	ISO 8601	End of the search window
`limit`	integer	Max results (1–500). Default: 100

Example Request

                  JSON
                  
                
{
  "query": "service.name = \"payment-svc\" AND status = ERROR",
  "start_time": "2026-03-15T00:00:00Z",
  "end_time": "2026-03-15T12:00:00Z",
  "limit": 50
}

Collector Nodes #

Monitor and manage Mesh-Trace collector nodes deployed across your clusters.

GET /v1/nodes List collector nodes

Example Response

                  JSON
                  
                
{
  "nodes": [
    {
      "node_id": "node-eu-central-1a-07",
      "cluster": "prod-eu-1",
      "version": "3.2.1",
      "status": "healthy",
      "spans_ingested_1h": 284910,
      "cpu_percent": 12.4,
      "memory_mb": 256,
      "last_heartbeat": "2026-03-15T09:41:58Z"
    }
  ],
  "total": 14
}

GET /v1/nodes/{node_id}/health Detailed node health metrics

Path Parameters

Parameter	Type	Description
`node_id` required	string	Unique node identifier

Example Response

                  JSON
                  
                
{
  "node_id": "node-eu-central-1a-07",
  "status": "healthy",
  "uptime_seconds": 604821,
  "ingestion_rate_sps": 4782,
  "dropped_spans_1h": 0,
  "otlp_grpc_active": true,
  "otlp_http_active": true,
  "sampling_rate": 0.15,
  "buffer_utilization_pct": 8.2
}

Services #

Discover services and explore the dependency topology of your infrastructure.

GET /v1/services List discovered services

Example Response

                  JSON
                  
                
{
  "services": [
    {
      "name": "api-gateway",
      "namespace": "default",
      "cluster": "prod-eu-1",
      "first_seen": "2026-01-08T14:30:00Z",
      "span_count_24h": 1482039,
      "error_rate_24h": 0.0012,
      "p99_latency_ms": 89
    }
  ],
  "total": 47
}

GET /v1/topology Service dependency graph

Query Parameters

Parameter	Type	Description
`cluster`	string	Filter by cluster name
`time_window`	string	Aggregation window: `1h`, `6h`, `24h`. Default: `1h`

Example Response

                  JSON
                  
                
{
  "nodes": [
    { "id": "api-gateway", "type": "service" },
    { "id": "order-svc", "type": "service" },
    { "id": "postgres-orders", "type": "database" }
  ],
  "edges": [
    {
      "source": "api-gateway",
      "target": "order-svc",
      "request_count": 48201,
      "error_rate": 0.002,
      "p50_latency_ms": 12,
      "p99_latency_ms": 45
    }
  ]
}

Alerts #

Create and manage alerting rules to get notified about anomalies in your traced services.

POST /v1/alerts/rules Create an alert rule

Request Body

Field	Type	Description
`name` required	string	Human-readable alert name
`condition` required	object	Trigger condition (metric, threshold, window)
`channels` required	array	Notification channels: `slack`, `email`, `pagerduty`, `webhook`
`severity`	string	`critical`, `warning`, or `info`. Default: `warning`

Example Request

                  JSON
                  
                
{
  "name": "Payment service high error rate",
  "condition": {
    "metric": "error_rate",
    "service": "payment-svc",
    "operator": ">",
    "threshold": 0.05,
    "window": "5m"
  },
  "channels": ["slack", "pagerduty"],
  "severity": "critical"
}

Example Response

                  JSON — 201 Created
                  
                
{
  "id": "alert_rule_7f3a8b2e",
  "name": "Payment service high error rate",
  "status": "active",
  "created_at": "2026-03-15T09:45:00Z"
}

Changelog #

Recent API changes and version history.

2026-03-10

New Service topology endpoint

Added GET /v1/topology for querying the service dependency graph with time-windowed aggregation.

2026-02-28

Improvement Trace search performance

Trace search queries now execute up to 3x faster with improved indexing on span attributes.

2026-02-15

New Alert rules API

Create, update, and delete alert rules programmatically via POST /v1/alerts/rules.

2026-01-20

Fix Pagination cursor stability

Fixed an issue where pagination cursors could become invalid when new traces were ingested between page requests.

2026-01-05

Breaking API v2 deprecated

API v2 endpoints have been removed. All integrations must migrate to v3. See the migration guide for details.

API Reference

Quick Start with cURL

Python SDK

Node.js SDK

Authentication #

Bearer Token

Base URL #

Rate Limits #

1,000 requests per minute

Error Handling #

SDKs & Libraries #

Python

Node.js / TypeScript

Go

Ruby

Traces #

Query Parameters

Example Response

Path Parameters

Example Response

Request Body

Example Request

Collector Nodes #

Example Response

Path Parameters

Example Response

Services #

Example Response

Query Parameters

Example Response

Alerts #

Request Body

Example Request

Example Response

Changelog #

New Service topology endpoint

Improvement Trace search performance

New Alert rules API

Fix Pagination cursor stability

Breaking API v2 deprecated