---
title: "Adaptive Traces HTTP API | Grafana Cloud documentation"
description: "Use the Adaptive Traces HTTP API to manage your sampling policies and recommendations at scale and integrate them into your existing infrastructure-as-code workflows."
---

# 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.

> Note
> 
> You can create [Grafana Cloud Access Policies](../../../../security-and-account-management/authentication-and-permissions/access-policies/#use-with-the-api-grafana-stacks-and-cloud-portal) from the Grafana portal, with the API, or in your Grafana Cloud Stack.

### The format of a sampling policy

Each sampling policy looks similar to this:

JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```json
{
  "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](/docs/grafana-cloud/adaptive-telemetry/adaptive-traces/reference/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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

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

The response is an array of policy objects:

JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```json
[
  {
    "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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```json
{
  "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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

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

> Note
> 
> Recommendations are generated asynchronously; the API call returns the most recently generated set of recommendations.

The response is an array of recommendation objects:

JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```json
[
  {
    "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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
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.