Create an Auto Monitor Setup

Trigger a process that attempts to create a Traceloop monitor using the provided selector criteria

POST /v2/auto-monitor-setups

Create an Auto Monitor Setup

cURL

curl --request POST \
  --url https://app.traceloop.com/api/v2/auto-monitor-setups \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "external_id": "<string>",
  "evaluators": [
    "<string>"
  ],
  "selector": [
    {}
  ]
}
'

An auto monitor setup is an asynchronous process that attempts to create a Traceloop monitor based on the selector you provide. The selector is matched against your incoming spans — when a match is found, the monitor is created and the specified evaluators begin running on those spans.

All API requests require authentication. Pass your API key as a Bearer token in the Authorization header. See Authentication for details.

Request Body

external_id · string · required

Unique identifier for the auto monitor setup. Used to reference it in future requests (get, update, delete).

Example: "my-agent-monitor-1"

evaluators · string[] · required

List of evaluator slugs to run on matched spans. Must contain at least one evaluator.

Example: ["answer-relevancy", "toxicity-detector"]

See the full list of available slugs in the Evaluator Slugs reference.

selector · object[]

An array of filter rules used to match spans. Each rule specifies an attribute key, a value to match, and a source indicating where the attribute lives. Only spans matching all provided rules will be evaluated.

Each rule has the following fields:

Field	Type	Required	Description
key	string	Yes	The attribute key to filter on (e.g., gen_ai.system, service.name)
value	string	Conditional	The value to match against. Required for equals, not_equals, contains, not_contains operators
values	string[]	Conditional	List of values to match against. Required for in, not_in operators
source	string	Yes	Where the attribute lives: span_attributes or resource_attributes
operator	string	No	Comparison operator. Defaults to equals. One of: equals, not_equals, contains, not_contains, exists, not_exists, in, not_in

All available span and resource attributes can be found in your Traceloop traces page.

Example Request

curl -X POST https://api.traceloop.com/v2/auto-monitor-setups \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "my-agent-monitor-1",
    "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"}
    ]
  }'

Response

201 Created

Returns the created auto monitor setup object. The init_rules array reflects the stored selector — same shape as the input selector.

{
  "id": "cmm...",
  "external_id": "my-agent-monitor-1",
  "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",
      "input_schema": [
        { "type": "string", "name": "completion", "description": "The LLM response to evaluate" },
        { "type": "string", "name": "context", "description": "The context for the answer" },
        { "type": "string", "name": "question", "description": "The original question" }
      ],
      "output_schema": [
        { "type": "float", "name": "answer_relevancy_score", "description": "Relevancy score (0-1)" }
      ],
      "status": "pending"
    },
    {
      "evaluator_type": "toxicity-detector",
      "input_schema": [
        { "type": "string", "name": "text", "description": "The text to analyze for toxicity" }
      ],
      "output_schema": [
        { "type": "boolean", "name": "is_toxic", "description": "Whether the text is toxic" }
      ],
      "status": "pending"
    }
  ],
  "status": "pending",
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-01-15T10:30:00Z"
}

400 Bad Request

Returned when the request body is invalid (e.g. missing required fields or empty evaluators array).

{
  "error": "invalid input: evaluators must contain at least one item"
}

500 Internal Server Error

{
  "error": "internal server error"
}