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

# Bulk Upsert Auto Monitor Setups

> Create or update up to 100 auto monitor setups in a single request, keyed by external_id

Creates or updates up to 100 [auto monitor setups](/monitoring/introduction) in one request, keyed by `external_id`. Designed for IaC-style clients that would otherwise fan out one HTTP call per setup.

Each item is upserted independently using the same semantics as [Update by External ID](/api-reference/auto-monitor-setups/update-an-auto-monitor-setup-by-external-id): if a setup with the given `external_id` exists in the project it is replaced (status reset to `pending`, evaluators replaced wholesale); otherwise it is created.

<Note>
  All API requests require authentication. Pass your API key as a Bearer token in the `Authorization` header.
  See [Authentication](/api-reference/introduction) for details.
</Note>

## Atomic Semantics

The batch is applied **atomically** — it either fully succeeds or nothing is written. If any item fails validation, or the database write fails, **no** setups are persisted. On success the endpoint returns **`200 OK`** with the full list of upserted setups.

Because the batch is all-or-nothing, there are no per-item status flags: every item in the response was written successfully. Failures are surfaced as a single request-level error (`400` or `500`) identifying the first offending item.

## Request Body

<ParamField body="setups" type="object[]" required>
  Array of setups to upsert. Must contain between 1 and 100 items. Each item has the same shape as the [Create](/api-reference/auto-monitor-setups/create-an-auto-monitor-setup) request body:

  | Field               | Type      | Required | Description                                                                                                                                                    |
  | ------------------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `external_id`       | string    | Yes      | Unique identifier for the setup within the project. Must be unique across items in the same batch.                                                             |
  | `evaluators`        | string\[] | Yes      | List of evaluator slugs to run on matched spans. See [Evaluator Slugs](/evaluators/evaluator-slugs).                                                           |
  | `selector`          | object\[] | No       | Array of filter rules used to match spans. See the [Create](/api-reference/auto-monitor-setups/create-an-auto-monitor-setup) endpoint for the selector schema. |
  | `evaluator_configs` | object\[] | No       | Optional per-evaluator configuration overrides.                                                                                                                |
</ParamField>

## Example Request

```bash theme={null}
curl -X POST https://api.traceloop.com/v2/auto-monitor-setups/bulk \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "setups": [
      {
        "external_id": "openai-gpt4o-monitor",
        "evaluators": ["answer-relevancy", "toxicity-detector"],
        "selector": [
          {"key": "gen_ai.system", "value": "openai", "source": "span_attributes"},
          {"key": "gen_ai.request.model", "value": "gpt-4o", "source": "span_attributes"}
        ]
      },
      {
        "external_id": "anthropic-monitor",
        "evaluators": ["answer-relevancy"],
        "selector": [
          {"key": "gen_ai.system", "value": "anthropic", "source": "span_attributes"}
        ]
      }
    ]
  }'
```

## Response

### 200 OK

Returned when the entire batch is upserted successfully. The `setups` array contains one entry per input item, in the **same order** as the request. Each entry is a full setup object, matching the [Create](/api-reference/auto-monitor-setups/create-an-auto-monitor-setup) response shape.

```json theme={null}
{
  "setups": [
    {
      "id": "cmm...",
      "external_id": "openai-gpt4o-monitor",
      "org_id": "c108269c-...",
      "project_id": "cm9v2g95l...",
      "env_project_id": "cm9v2ga9i...",
      "init_rules": [
        { "key": "gen_ai.system", "value": "openai", "source": "span_attributes", "operator": "equals" },
        { "key": "gen_ai.request.model", "value": "gpt-4o", "source": "span_attributes", "operator": "equals" }
      ],
      "evaluators": [
        { "evaluator_type": "answer-relevancy", "status": "pending" },
        { "evaluator_type": "toxicity-detector", "status": "pending" }
      ],
      "status": "pending",
      "created_at": "2026-05-20T10:30:00Z",
      "updated_at": "2026-05-20T10:30:00Z"
    },
    {
      "id": "cmm...",
      "external_id": "anthropic-monitor",
      "org_id": "c108269c-...",
      "project_id": "cm9v2g95l...",
      "env_project_id": "cm9v2ga9i...",
      "init_rules": [
        { "key": "gen_ai.system", "value": "anthropic", "source": "span_attributes", "operator": "equals" }
      ],
      "evaluators": [
        { "evaluator_type": "answer-relevancy", "status": "pending" }
      ],
      "status": "pending",
      "created_at": "2026-05-20T10:30:00Z",
      "updated_at": "2026-05-20T10:30:00Z"
    }
  ]
}
```

### 400 Bad Request

Returned when the batch is rejected without writing any items. The `error` message identifies the first offending item by index. Causes:

* Empty `setups` array — `setups must contain at least 1 item`
* More than 100 items — `setups exceeds max of 100`
* Any item missing `external_id` — `setups[N]: external_id is required`
* Two items in the batch share the same `external_id` — `setups[N]: duplicate external_id "..." (also at setups[M])`
* Any item fails validation — e.g. an unknown evaluator slug, an invalid selector, or an invalid evaluator config, prefixed with the item index: `setups[N]: evaluators[0]: unknown evaluator slug "..."`

```json theme={null}
{
  "error": "setups[2]: duplicate external_id \"openai-gpt4o-monitor\" (also at setups[0])"
}
```

### 500 Internal Server Error

Returned when the database write fails. No items are persisted. The underlying cause is logged server-side and not returned to the client.

```json theme={null}
{
  "error": "Internal server error"
}
```