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

# Create an alert

> Create a threshold alert in a project the authenticated user can write to.

Requires MEMBER role or higher in the project's workspace (the write
service decides). Strict create — alerts have no unique name, so every
call inserts and ``created`` is always ``true`` on success.

Args:
    request (Request): Incoming request (rate-limit plumbing).
    response (Response): Outgoing response (rate-limit plumbing).
    auth (AccountStampedAuth): Account-scope user auth (session token or
        CLI access JWT); its resolved ``user_id`` becomes the actor.
    payload (CreateAlertRequest): The alert rule to create.
    _live (None): Write-path liveness gate (blocks a revoked JWT session).

Returns:
    CreateAlertResponse: The created alert with its full rule.



## OpenAPI

````yaml /api-reference/openapi.json post /api/v1/public/alerts
openapi: 3.1.0
info:
  title: TraceRoot Public API
  version: 0.1.0
servers:
  - description: TraceRoot Cloud
    url: https://app.traceroot.ai
  - description: Self-hosted
    url: '{baseUrl}'
    variables:
      baseUrl:
        default: http://localhost:8000
        description: Your TraceRoot backend URL
security: []
paths:
  /api/v1/public/alerts:
    post:
      tags:
        - Alerts
      summary: Create an alert
      description: >-
        Create a threshold alert in a project the authenticated user can write
        to.


        Requires MEMBER role or higher in the project's workspace (the write

        service decides). Strict create — alerts have no unique name, so every

        call inserts and ``created`` is always ``true`` on success.


        Args:
            request (Request): Incoming request (rate-limit plumbing).
            response (Response): Outgoing response (rate-limit plumbing).
            auth (AccountStampedAuth): Account-scope user auth (session token or
                CLI access JWT); its resolved ``user_id`` becomes the actor.
            payload (CreateAlertRequest): The alert rule to create.
            _live (None): Write-path liveness gate (blocks a revoked JWT session).

        Returns:
            CreateAlertResponse: The created alert with its full rule.
      operationId: create_alert
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAlertRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAlertResponse'
          description: Successful Response
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Authentication failed or session revoked
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient role or wrong credential kind
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: The project has reached its alert limit
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Write service unavailable
      security:
        - BearerAuth: []
components:
  schemas:
    CreateAlertRequest:
      description: Body for creating a threshold alert in a project.
      properties:
        aggregation:
          enum:
            - sum
            - avg
            - count
            - max
            - min
            - p50
            - p75
            - p90
            - p95
            - p99
            - uniq
          title: Aggregation
          type: string
        filters:
          description: Row predicates the measure is evaluated over
          items:
            $ref: '#/components/schemas/AlertFilterItemRequest'
          title: Filters
          type: array
        measure:
          description: A measure of the view, e.g. latency, cost, count
          title: Measure
          type: string
        name:
          title: Name
          type: string
        no_data_mode:
          anyOf:
            - enum:
                - HOLD
                - ZERO
                - NOTIFY
              type: string
            - type: 'null'
          description: >-
            What a window that measured nothing means; column default when
            omitted
          title: No Data Mode
        project_id:
          title: Project Id
          type: string
        renotify:
          $ref: '#/components/schemas/AlertRenotifyRequest'
        threshold:
          title: Threshold
          type: number
        threshold_operator:
          enum:
            - '>'
            - '>='
            - <
            - <=
            - '='
            - '!='
          title: Threshold Operator
          type: string
        view:
          const: SPANS
          title: View
          type: string
        window:
          enum:
            - 1m
            - 5m
            - 10m
            - 30m
            - 1h
            - 2h
          title: Window
          type: string
      required:
        - project_id
        - name
        - view
        - measure
        - aggregation
        - window
        - threshold_operator
        - threshold
        - renotify
      title: CreateAlertRequest
      type: object
    CreateAlertResponse:
      description: >-
        The created alert with its full rule (alert creation is strict, never
        idempotent).
      properties:
        alert:
          $ref: '#/components/schemas/AlertDetail'
        created:
          title: Created
          type: boolean
      required:
        - created
        - alert
      title: CreateAlertResponse
      type: object
    ErrorResponse:
      description: >-
        The canonical public error envelope (matches the gateway's normalized
        shape).
      properties:
        detail:
          title: Detail
          type: string
      required:
        - detail
      title: ErrorResponse
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    AlertFilterItemRequest:
      additionalProperties: false
      description: A row predicate an alert's measure is evaluated over.
      properties:
        field:
          description: A span field, e.g. model_name or metadata
          title: Field
          type: string
        key:
          description: The map entry to compare; required for the metadata field
          title: Key
          type: string
        op:
          enum:
            - '='
            - contains
          title: Op
          type: string
        value:
          title: Value
          type:
            - string
            - number
      required:
        - field
        - op
        - value
      title: AlertFilterItemRequest
      type: object
    AlertRenotifyRequest:
      description: How often an alert re-notifies while it stays in the alerting state.
      properties:
        interval_minutes:
          description: Minutes between repeat notifications; required when mode is EVERY
          title: Interval Minutes
          type: integer
        mode:
          enum:
            - 'OFF'
            - EVERY
          title: Mode
          type: string
      required:
        - mode
      title: AlertRenotifyRequest
      type: object
    AlertDetail:
      description: 'One alert with its full rule: the summary plus filters and gap handling.'
      properties:
        aggregation:
          title: Aggregation
          type: string
        alerted_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Alerted At
        create_time:
          format: date-time
          title: Create Time
          type: string
        creator:
          anyOf:
            - type: string
            - type: 'null'
          title: Creator
        filters:
          items:
            $ref: '#/components/schemas/AlertFilterItem'
          title: Filters
          type: array
        id:
          title: Id
          type: string
        last_error:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Error
        last_error_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Last Error At
        last_evaluated_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Last Evaluated At
        last_notify_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Last Notify At
        last_notify_error:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Notify Error
        last_notify_status:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Notify Status
        measure:
          title: Measure
          type: string
        name:
          title: Name
          type: string
        no_data_mode:
          title: No Data Mode
          type: string
        renotify:
          $ref: '#/components/schemas/AlertRenotify'
        severity:
          title: Severity
          type: string
        severity_changed_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Severity Changed At
        status:
          title: Status
          type: string
        threshold:
          title: Threshold
          type: number
        threshold_operator:
          title: Threshold Operator
          type: string
        update_time:
          format: date-time
          title: Update Time
          type: string
        view:
          title: View
          type: string
        window:
          title: Window
          type: string
      required:
        - id
        - name
        - view
        - measure
        - aggregation
        - window
        - threshold_operator
        - threshold
        - status
        - severity
        - severity_changed_at
        - alerted_at
        - last_evaluated_at
        - last_error
        - last_error_at
        - last_notify_status
        - last_notify_error
        - last_notify_at
        - create_time
        - update_time
        - creator
        - filters
        - renotify
        - no_data_mode
      title: AlertDetail
      type: object
    ValidationError:
      properties:
        ctx:
          title: Context
          type: object
        input:
          title: Input
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
      type: object
    AlertFilterItem:
      description: |-
        A row predicate an alert's measure is evaluated over.

        Mirrors the alert filter vocabulary in the frontend core package: ``op``
        is one of the two alert operators, and ``key`` names the map entry on a
        keyed field (metadata).
      properties:
        field:
          title: Field
          type: string
        key:
          anyOf:
            - type: string
            - type: 'null'
          title: Key
        op:
          enum:
            - '='
            - contains
          title: Op
          type: string
        value:
          anyOf:
            - type: string
            - type: number
          title: Value
      required:
        - field
        - op
        - value
      title: AlertFilterItem
      type: object
    AlertRenotify:
      description: |-
        How often an alert re-notifies while it stays in the alerting state.

        Kept a single-level object rather than a discriminated union, matching
        the request-side shape. The cross-field rule is enforced by a validator
        instead, so a contradictory stored rule fails the detail read closed
        rather than passing through half-typed.
      properties:
        interval_minutes:
          anyOf:
            - type: integer
            - type: 'null'
          title: Interval Minutes
        mode:
          enum:
            - 'OFF'
            - EVERY
          title: Mode
          type: string
      required:
        - mode
      title: AlertRenotify
      type: object
  securitySchemes:
    BearerAuth:
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.