---
title: "POST /api/v1/config/trace-behaviors"
method: POST
path: "/api/v1/config/trace-behaviors"
tags: ["TraceBehavior"]
---

# POST /api/v1/config/trace-behaviors

`POST /api/v1/config/trace-behaviors`

## Request body

- Configv1CreateTraceBehaviorRequest
  - `dry_run` boolean — If `true`, validates the specified configuration without creating the TraceBehavior. If the specified configuration is valid, the endpoint returns a partial response without the TraceBehavior. If the specified configuration is invalid, the endpoint returns an error.
  - `trace_behavior` Configv1TraceBehavior
    - `base_head_sample_rate` number, double — Specifies the sample rate for head sampling. This rate applies to all root spans that are enrolled in head sampling, but don't have a specific rule defined for their service.
    - `base_tail_sample_rate` number, double — Specifies the base sample rate for fully assembled traces that don't apply to the `error_sample_options`, `fast_sample_options`, `slow_sample_options`, `large_trace_sample_options`, or `small_trace_sample_options` sampling options.
    - `created_at` string, date-time — Timestamp of when the TraceBehavior was created. Cannot be set by clients.
    - `description` string
    - `error_sample_options` TraceBehaviorErrorSampleOptions
      - `enabled` boolean — Determines whether or not to define options for error traces.
      - `sample_rate` number, double — Specifies the sample rate for traces with errors.
      - `sampling_type` 'LOW_VALUE' | 'HIGH_VALUE' — - LOW_VALUE: Match indicates a low value trace. With multiple low value matches sample at the lowest rate. - HIGH_VALUE: Match indicates a high value trace. With multiple high value matches sample at the highest rate.
    - `fast_sample_options` TraceBehaviorFastSampleOptions
      - `enabled` boolean — Determines whether or not to define options for fast traces.
      - `max_duration_seconds` number, double — Duration in seconds under which traces are sampled according to the given sample rate.
      - `sample_rate` number, double — Defines the sample rate for traces during a specified duration.
      - `sampling_type` 'LOW_VALUE' | 'HIGH_VALUE' — - LOW_VALUE: Match indicates a low value trace. With multiple low value matches sample at the lowest rate. - HIGH_VALUE: Match indicates a high value trace. With multiple high value matches sample at the highest rate.
    - `large_trace_sample_options` TraceBehaviorLargeTraceSampleOptions
      - `enabled` boolean — Determines whether or not to define options for large traces.
      - `sample_rate` number, double — Defines the sample rate for traces during a specified duration.
      - `sampling_type` 'LOW_VALUE' | 'HIGH_VALUE' — - LOW_VALUE: Match indicates a low value trace. With multiple low value matches sample at the lowest rate. - HIGH_VALUE: Match indicates a high value trace. With multiple high value matches sample at the highest rate.
      - `span_count_threshold` integer — Defines the sampling rate for large traces. If the number of spans in the trace is grater than or equal to (`>=`) the `span_count_threshold`, the trace is sampled according to the given sample rate.
    - `name` string, required — The name of the TraceBehavior. You can modify this value after the TraceBehavior is created.
    - `slow_sample_options` TraceBehaviorSlowSampleOptions
      - `enabled` boolean — Determines whether or not to define options for slow traces.
      - `min_duration_seconds` number, double — Duration in seconds under which traces are sampled according to the given sample rate.
      - `sample_rate` number, double — Defines the sample rate for traces during a specified duration.
      - `sampling_type` 'LOW_VALUE' | 'HIGH_VALUE' — - LOW_VALUE: Match indicates a low value trace. With multiple low value matches sample at the lowest rate. - HIGH_VALUE: Match indicates a high value trace. With multiple high value matches sample at the highest rate.
    - `slug` string — The unique identifier of the TraceBehavior. If a `slug` isn't provided, one is generated based on the `name` field. You can't modify this field after the TraceBehavior is created.
    - `small_trace_sample_options` TraceBehaviorSmallTraceSampleOptions
      - `enabled` boolean — Determines whether or not to define options for small traces.
      - `sample_rate` number, double — Defines the sample rate for traces during a specified duration.
      - `sampling_type` 'LOW_VALUE' | 'HIGH_VALUE' — - LOW_VALUE: Match indicates a low value trace. With multiple low value matches sample at the lowest rate. - HIGH_VALUE: Match indicates a high value trace. With multiple high value matches sample at the highest rate.
      - `span_count_threshold` integer — Defines the sampling rate for small traces. If the number of spans in the trace is less than or equal to (`<=`) the `span_count_threshold`, the trace is sampled according to the given sample rate.
    - `updated_at` string, date-time — Timestamp of when the TraceBehavior was last updated. Cannot be set by clients.

## Response `200`

A successful response containing the created TraceBehavior.

- Configv1CreateTraceBehaviorResponse
  - `trace_behavior` Configv1TraceBehavior
    - `base_head_sample_rate` number, double — Specifies the sample rate for head sampling. This rate applies to all root spans that are enrolled in head sampling, but don't have a specific rule defined for their service.
    - `base_tail_sample_rate` number, double — Specifies the base sample rate for fully assembled traces that don't apply to the `error_sample_options`, `fast_sample_options`, `slow_sample_options`, `large_trace_sample_options`, or `small_trace_sample_options` sampling options.
    - `created_at` string, date-time — Timestamp of when the TraceBehavior was created. Cannot be set by clients.
    - `description` string
    - `error_sample_options` TraceBehaviorErrorSampleOptions
      - `enabled` boolean — Determines whether or not to define options for error traces.
      - `sample_rate` number, double — Specifies the sample rate for traces with errors.
      - `sampling_type` 'LOW_VALUE' | 'HIGH_VALUE' — - LOW_VALUE: Match indicates a low value trace. With multiple low value matches sample at the lowest rate. - HIGH_VALUE: Match indicates a high value trace. With multiple high value matches sample at the highest rate.
    - `fast_sample_options` TraceBehaviorFastSampleOptions
      - `enabled` boolean — Determines whether or not to define options for fast traces.
      - `max_duration_seconds` number, double — Duration in seconds under which traces are sampled according to the given sample rate.
      - `sample_rate` number, double — Defines the sample rate for traces during a specified duration.
      - `sampling_type` 'LOW_VALUE' | 'HIGH_VALUE' — - LOW_VALUE: Match indicates a low value trace. With multiple low value matches sample at the lowest rate. - HIGH_VALUE: Match indicates a high value trace. With multiple high value matches sample at the highest rate.
    - `large_trace_sample_options` TraceBehaviorLargeTraceSampleOptions
      - `enabled` boolean — Determines whether or not to define options for large traces.
      - `sample_rate` number, double — Defines the sample rate for traces during a specified duration.
      - `sampling_type` 'LOW_VALUE' | 'HIGH_VALUE' — - LOW_VALUE: Match indicates a low value trace. With multiple low value matches sample at the lowest rate. - HIGH_VALUE: Match indicates a high value trace. With multiple high value matches sample at the highest rate.
      - `span_count_threshold` integer — Defines the sampling rate for large traces. If the number of spans in the trace is grater than or equal to (`>=`) the `span_count_threshold`, the trace is sampled according to the given sample rate.
    - `name` string, required — The name of the TraceBehavior. You can modify this value after the TraceBehavior is created.
    - `slow_sample_options` TraceBehaviorSlowSampleOptions
      - `enabled` boolean — Determines whether or not to define options for slow traces.
      - `min_duration_seconds` number, double — Duration in seconds under which traces are sampled according to the given sample rate.
      - `sample_rate` number, double — Defines the sample rate for traces during a specified duration.
      - `sampling_type` 'LOW_VALUE' | 'HIGH_VALUE' — - LOW_VALUE: Match indicates a low value trace. With multiple low value matches sample at the lowest rate. - HIGH_VALUE: Match indicates a high value trace. With multiple high value matches sample at the highest rate.
    - `slug` string — The unique identifier of the TraceBehavior. If a `slug` isn't provided, one is generated based on the `name` field. You can't modify this field after the TraceBehavior is created.
    - `small_trace_sample_options` TraceBehaviorSmallTraceSampleOptions
      - `enabled` boolean — Determines whether or not to define options for small traces.
      - `sample_rate` number, double — Defines the sample rate for traces during a specified duration.
      - `sampling_type` 'LOW_VALUE' | 'HIGH_VALUE' — - LOW_VALUE: Match indicates a low value trace. With multiple low value matches sample at the lowest rate. - HIGH_VALUE: Match indicates a high value trace. With multiple high value matches sample at the highest rate.
      - `span_count_threshold` integer — Defines the sampling rate for small traces. If the number of spans in the trace is less than or equal to (`<=`) the `span_count_threshold`, the trace is sampled according to the given sample rate.
    - `updated_at` string, date-time — Timestamp of when the TraceBehavior was last updated. Cannot be set by clients.

## Other responses

- `400` — Cannot create the TraceBehavior because the request is invalid.
- `409` — Cannot create the TraceBehavior because there is a conflict with an existing TraceBehavior.
- `500` — An unexpected error response.
- `default` — An undefined error response.

---

[API](https://skmtc.dev/chronosphere/apis/data-v1-api.md) · [All operations](https://skmtc.dev/chronosphere/apis/data-v1-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/chronosphere/data-v1-api/revisions/ee91fd539ced/schema)