> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fiddler.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API

> Reference for the Fiddler REST API. Every operation in the public OpenAPI specification is documented here, grouped by resource.

The Fiddler REST API is organized around REST: it has predictable, resource-oriented URLs, accepts and returns JSON-encoded payloads, and uses standard HTTP response codes, authentication, and verbs. Use it to ingest events, manage models, configure alerts, run explainability queries, and more.

<Tip>
  All endpoints require Bearer token authentication. See [Authentication](/sdk-api/python-client/connection) for details on obtaining a token.
</Tip>

<CardGroup cols={3}>
  <Card title="Alert Rules" href="/sdk-api/rest-api/alert-rules">
    `/alert-rules` endpoints
  </Card>

  <Card title="Applications" href="/sdk-api/rest-api/applications">
    `/applications` endpoints
  </Card>

  <Card title="Attributes" href="/sdk-api/rest-api/attributes">
    `/attributes` endpoints
  </Card>

  <Card title="Baselines" href="/sdk-api/rest-api/baseline">
    `/baseline` endpoints
  </Card>

  <Card title="Custom Metrics" href="/sdk-api/rest-api/custom-metrics">
    `/custom-metrics` endpoints
  </Card>

  <Card title="Environments" href="/sdk-api/rest-api/environment">
    `/environment` endpoints
  </Card>

  <Card title="Evals" href="/sdk-api/rest-api/evals">
    `/evals` endpoints
  </Card>

  <Card title="Evaluation" href="/sdk-api/rest-api/evaluation">
    `/evaluation` endpoints
  </Card>

  <Card title="Evaluator Rules" href="/sdk-api/rest-api/evaluator-rules">
    `/evaluator-rules` endpoints
  </Card>

  <Card title="Evaluators" href="/sdk-api/rest-api/evaluators">
    `/evaluators` endpoints
  </Card>

  <Card title="Events" href="/sdk-api/rest-api/events">
    `/events` endpoints
  </Card>

  <Card title="Experiments" href="/sdk-api/rest-api/experiments">
    `/experiments` endpoints
  </Card>

  <Card title="File Upload" href="/sdk-api/rest-api/file-upload">
    `/file-upload` endpoints
  </Card>

  <Card title="FQL Expressions" href="/sdk-api/rest-api/fql-expressions">
    `/fql-expressions` endpoints
  </Card>

  <Card title="GenAI Alert Rules" href="/sdk-api/rest-api/genai-alert-rules">
    `/genai-alert-rules` endpoints
  </Card>

  <Card title="Jobs" href="/sdk-api/rest-api/jobs">
    `/jobs` endpoints
  </Card>

  <Card title="LLM Gateway" href="/sdk-api/rest-api/llm-gateway">
    `/llm-gateway` endpoints
  </Card>

  <Card title="Models" href="/sdk-api/rest-api/model">
    `/model` endpoints
  </Card>

  <Card title="Projects" href="/sdk-api/rest-api/projects">
    `/projects` endpoints
  </Card>

  <Card title="Queries" href="/sdk-api/rest-api/queries">
    `/queries` endpoints
  </Card>

  <Card title="Segments" href="/sdk-api/rest-api/segments">
    `/segments` endpoints
  </Card>

  <Card title="Server Info" href="/sdk-api/rest-api/server-info">
    `/server-info` endpoints
  </Card>

  <Card title="Sessions" href="/sdk-api/rest-api/sessions">
    `/sessions` endpoints
  </Card>

  <Card title="Spans" href="/sdk-api/rest-api/spans">
    `/spans` endpoints
  </Card>

  <Card title="Traces" href="/sdk-api/rest-api/traces">
    `/traces` endpoints
  </Card>

  <Card title="User Access Keys" href="/sdk-api/rest-api/user-access-keys">
    `/user-access-keys` endpoints
  </Card>

  <Card title="Users" href="/sdk-api/rest-api/users">
    `/users` endpoints
  </Card>
</CardGroup>

## API Response types

Every Fiddler API response is wrapped in an envelope whose `kind` field identifies the response type: `NORMAL`, `PAGINATED`, or `ERROR`.

### Normal response

Returned by operations that respond with a single resource or result. The payload is carried in `data`.

```json theme={null}
{
  "api_version": "3.0",
  "kind": "NORMAL",
  "data": {}
}
```

### Paginated response

Returned by list operations. The `data` object carries the current page in `items`, alongside pagination metadata.

```json theme={null}
{
  "api_version": "3.0",
  "kind": "PAGINATED",
  "data": {
    "page_size": 10,
    "item_count": 10,
    "total": 100,
    "page_count": 10,
    "page_index": 1,
    "offset": 0,
    "items": []
  }
}
```

### Error response

Returned when a request fails. The `error` object carries an HTTP-aligned `code`, a human-readable `message`, and an `errors` array with per-issue detail.

```json theme={null}
{
  "api_version": "3.0",
  "kind": "ERROR",
  "error": {
    "code": 404,
    "message": "The requested resource was not found.",
    "errors": [
      {
        "reason": "ResourceNotFound",
        "message": "Model 'abc123' was not found in this project.",
        "help": ""
      }
    ]
  }
}
```

## Rate Limiting

Rate limits apply to the endpoint categories listed below. When a limit is exceeded, the API returns **`429 Too Many Requests`**. These are **default limits and are deployment-overridable** — your Fiddler administrator can tune them per environment, and rate limiting can be enabled or disabled per deployment.

### Default limits

| Endpoint category                                                                                                            | Limit                   |
| ---------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| Metadata **read** — `GET` (list/read) on projects, applications, evaluators, evaluator rules, and related metadata resources | 30 req/s, 1,000 req/min |
| Metadata **write** — `POST`/`PATCH`/`DELETE` on the same resources                                                           | 10 req/s, 300 req/min   |
| Spans query — `POST /v3/spans/query`                                                                                         | 10 req/s, 120 req/min   |
| ML event deletion — `DELETE /v3/events`                                                                                      | 30 req/day              |
| GenAI bulk delete — `DELETE /v3/traces`, `DELETE /v3/sessions`                                                               | 5 req/s, 100 req/day    |

### Response headers

Responses from rate-limited endpoints include the following headers:

| Header                  | Description                                                                     |
| ----------------------- | ------------------------------------------------------------------------------- |
| `X-RateLimit-Limit`     | The active rate-limit policy for the endpoint (for example, `30 per 1 second`). |
| `X-RateLimit-Remaining` | Requests remaining in the current window.                                       |
| `X-RateLimit-Reset`     | Unix timestamp (in seconds) at which the current window resets.                 |
| `Retry-After`           | Seconds to wait before retrying. Sent only on a `429` response.                 |

### Per-token limits

Limits are enforced **per access token**. Each endpoint keeps its own independent counter, so exhausting the limit on one endpoint does not consume the budget of any other.

### Handling 429 responses

When a request returns `429 Too Many Requests`, wait at least the number of seconds indicated by the `Retry-After` header, then retry using **exponential backoff with jitter**. Each operation that enforces a limit also documents its `429 Too Many Requests` response on its API reference page (see the resource groups above).