Skip to main content
POST
/
v2
/
auto-monitor-setups
Create an Auto Monitor Setup
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": [
    {}
  ]
}
'

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.

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:
FieldTypeRequiredDescription
keystringYesThe attribute key to filter on (e.g., gen_ai.system, service.name)
valuestringConditionalThe value to match against. Required for equals, not_equals, contains, not_contains operators
valuesstring[]ConditionalList of values to match against. Required for in, not_in operators
sourcestringYesWhere the attribute lives: span_attributes or resource_attributes
operatorstringNoComparison 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. The status field indicates the current state of the setup process:
StatusDescription
pendingThe setup has been created and is queued for processing
in_progressThe setup is actively being processed
waiting_for_spansThe setup is ready and waiting for enough spans to be received before attempting to process
completedAll monitors have been successfully created
partialSome monitors were created but others failed
failedThe setup process failed
{
  "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"
}