Documentation Grafana Cloud Adaptive Telemetry Adaptive Traces Manage as code Adaptive Traces API

Adaptive Traces HTTP API

The following topic describes the Adaptive Traces HTTP API.

Before you begin

To interact with the API, gather the following information:

• URL: In the form https://<your-grafana-cloud-tempo-url>.grafana.net. To find your URL value, go to your Grafana Cloud account and check the Details page of your hosted Tempo endpoint.
• TENANT: The numeric instance ID where you want to use Adaptive Traces. To find your TENANT value, go to your Grafana Cloud account and check the Details page of your hosted Tempo endpoint for Username / Instance ID.
• TOKEN: A token from a Grafana Cloud Access Policy that has the adaptive-traces:admin scope for your stack ID.

The format of a sampling policy

Each sampling policy looks similar to this:

JSON Copy

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "type": "probabilistic",
  "name": "Sample 10% of all traces",
  "body": {
    "sampling_percentage": 10
  },
  "expires_at": "2025-12-31T23:59:59Z",
  "version_created_at": "2025-01-15T10:30:00Z",
  "version_created_by": "user@example.com"
}

In the preceding example:

• id is the unique identifier of the policy (set by the server).
• type is the type of sampling policy. Refer to Policy types for a list of available types.
• name is a human-readable name for the policy.
• body is a JSON object containing the policy-specific configuration. The structure depends on the type.
• expires_at (optional) is an ISO 8601 timestamp indicating when the policy expires.
• version_created_at is the timestamp when the current version of the policy was created.
• version_created_by is the user who created the current version of the policy.

Policies

List policies

List all sampling policies using the following command:

Bash Copy

curl -u "$TENANT:$TOKEN" "$URL/adaptive-traces/api/v1/policies"

The response is an array of policy objects:

JSON Copy

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "type": "probabilistic",
    "name": "Sample 10% of all traces",
    "body": {
      "sampling_percentage": 10
    },
    "version_created_at": "2025-01-15T10:30:00Z",
    "version_created_by": "user@example.com"
  },
  {
    "id": "987fcdeb-51a2-12d3-a456-426614174000",
    "type": "status_code",
    "name": "Keep all error traces",
    "body": {
      "status_codes": ["ERROR"]
    },
    "version_created_at": "2025-01-15T10:35:00Z",
    "version_created_by": "user@example.com"
  }
]

Get a policy

Get a specific policy by ID:

Bash Copy

curl -u "$TENANT:$TOKEN" "$URL/adaptive-traces/api/v1/policies/<policy_id>"

Replace <policy_id> with the UUID of the policy to retrieve.

Create a policy

Create a new sampling policy:

Bash Copy

curl -u "$TENANT:$TOKEN" --request POST \
  --header "Content-Type: application/json" \
  --data @policy.json \
  "$URL/adaptive-traces/api/v1/policies"

The request body must include the type, name, and body fields. For example, the contents of policy.json:

JSON Copy

{
  "type": "probabilistic",
  "name": "Sample 5% of all traces",
  "body": {
    "sampling_percentage": 5
  }
}

If successful, the server returns the created policy including its server-assigned id.

Update a policy

Update an existing policy by ID:

Bash Copy

curl -u "$TENANT:$TOKEN" --request PUT \
  --header "Content-Type: application/json" \
  --data @policy.json \
  "$URL/adaptive-traces/api/v1/policies/<policy_id>"

Replace <policy_id> with the UUID of the policy to update. The request body must include the full policy definition (type, name, and body fields).

Delete a policy

Delete a policy by ID:

Bash Copy

curl -u "$TENANT:$TOKEN" --request DELETE \
  "$URL/adaptive-traces/api/v1/policies/<policy_id>"

Replace <policy_id> with the UUID of the policy to delete.

Recommendations

Adaptive Traces generates recommendations for sampling policies based on your trace data. You can list, apply, or dismiss recommendations using the API.

List recommendations

List all sampling recommendations:

Bash Copy

curl -u "$TENANT:$TOKEN" "$URL/adaptive-traces/api/v1/recommendations"

The response is an array of recommendation objects:

JSON Copy

[
  {
    "id": "abc12345-e89b-12d3-a456-426614174000",
    "message": "Add a probabilistic sampling policy for service 'frontend'",
    "tags": ["cost-reduction"],
    "created_at": "2025-01-15T10:30:00Z",
    "applied": false,
    "dismissed": false,
    "stale": false,
    "actions": [
      {
        "action": "create",
        "recommendation_seed_id": "seed-001",
        "seed": {
          "id": "seed-001",
          "type": "probabilistic",
          "name": "Sample frontend traces",
          "body": {
            "sampling_percentage": 10
          }
        }
      }
    ]
  }
]

Each recommendation contains one or more actions that describe the policy changes that are applied when the recommendation is accepted. The possible action types are create, update, and delete.

Apply a recommendation

Apply a recommendation to modify policies according to its actions:

Bash Copy

curl -u "$TENANT:$TOKEN" --request POST \
  "$URL/adaptive-traces/api/v1/recommendations/<recommendation_id>/apply"

Replace <recommendation_id> with the UUID of the recommendation to apply.

Dismiss a recommendation

Dismiss a recommendation without applying it:

Bash Copy

curl -u "$TENANT:$TOKEN" --request POST \
  "$URL/adaptive-traces/api/v1/recommendations/<recommendation_id>/dismiss"

Replace <recommendation_id> with the UUID of the recommendation to dismiss.