---
title: "Adaptive Logs HTTP API | Grafana Cloud documentation"
description: "Use the Adaptive Logs HTTP API to manage your Adaptive Logs configuration at scale and integrate it into your existing infrastructure-as-code workflows."
---

# Adaptive Logs HTTP API

The following topic describes the Adaptive Logs HTTP API.

### Before you begin

To interact with the API, gather the following information:

- `URL`: In the form `https://<your-grafana-cloud-loki-url>.grafana.net`. To find your `URL` value, go to your Grafana Cloud account and check the **Details** page of your hosted Loki endpoint.
- `TENANT`: The numeric instance ID where you want to use Adaptive Logs. To find your `TENANT` value, go to your Grafana Cloud account and check the **Details** page of your hosted Loki endpoint for **Username / Instance ID**.
- `TOKEN`: A token from a Grafana Cloud Access Policy that has the **`adaptive-logs:admin`** scope for your stack. More details about available permissions and scopes can be found in [RBAC for Adaptive Logs](/docs/grafana-cloud/adaptive-telemetry/adaptive-logs/additional-configuration/adaptive-logs-rbac/).

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

### Patterns and recommendations

Adaptive Logs groups your log lines into patterns and generates recommendations for each pattern based on query usage over a rolling 15-day window. Each pattern has a drop rate that controls what percentage of matching log lines are dropped upon ingestion.

A recommendation looks similar to this:

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

```json
{
  "pattern": "level=info ts=<_> caller=<_> msg=\"request completed\" status=200 duration=<_>",
  "volume": "1.2 GiB",
  "query_frequency": "rarely",
  "current_drop_rate": 0,
  "recommended_drop_rate": 80,
  "projected_savings": "960 MiB"
}
```

In the preceding example:

- `pattern` is the detected log line pattern with variable portions replaced by placeholders.
- `volume` is the total ingested volume for this pattern over the past 15 days.
- `query_frequency` indicates how often this pattern is queried. Possible values are `never`, `rarely`, `sometimes`, `often`, and `always`.
- `current_drop_rate` is the percentage of log lines currently being dropped (0 to 100).
- `recommended_drop_rate` is the percentage that Adaptive Logs recommends dropping.
- `projected_savings` is the estimated savings based on the recommended rate.

#### List recommendations

Download recommendations for patterns and drop rates using the following command. `TOKEN` and `TENANT` are variables defined in the [requirements section](#before-you-begin).

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

```bash
curl -u "$TENANT:$TOKEN" "$URL/adaptive-logs/recommendations"
```

`TOKEN` must belong to an access policy with the **`adaptive-logs:admin`** scope.

> Note
> 
> Recommendations are generated asynchronously. The API call returns the most recently generated set of recommendations. Adaptive Logs recalculates recommendations every 24 hours.

### Exemptions

Exemptions allow you to prevent certain logs from being dropped, even if Adaptive Logs recommends dropping them. Exemptions are defined using LogQL stream selectors. You can also create temporary exemptions that expire after a set duration.

The exemption format looks like this:

Expand table

| Field name              | Type       | Description                                                                   |
|-------------------------|------------|-------------------------------------------------------------------------------|
| `id`                    | identifier | Unique identifier of the exemption (set by the server).                       |
| `stream_selector`       | string     | A valid LogQL stream selector. Logs matching this selector are never dropped. |
| `reason` (optional)     | string     | Business context for why this exemption exists.                               |
| `expires_at` (optional) | timestamp  | When this exemption expires. If not set, the exemption is permanent.          |
| `created_at`            | timestamp  | When the exemption was created (set by the server).                           |
| `updated_at`            | timestamp  | When the exemption was last updated (set by the server).                      |

Below are examples of exemptions:

1. Exempt all logs from the `login` service from being dropped.
   
   JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```json
   {
     "stream_selector": "{service_name=\"login\"}"
   }
   ```
2. Exempt all logs from the `payments` namespace with a reason.
   
   JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```json
   {
     "stream_selector": "{namespace=\"payments\"}",
     "reason": "Required for PCI compliance audit trail"
   }
   ```
3. Create a temporary exemption that expires after one hour.
   
   JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```json
   {
     "stream_selector": "{service_name=\"api-gateway\"}",
     "reason": "Investigating latency spike",
     "expires_at": "2025-04-21T15:00:00Z"
   }
   ```

#### Create an exemption

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

```bash
curl -u "$TENANT:$TOKEN" --request POST --data @exemption.json "$URL/adaptive-logs/exemptions"
```

`TOKEN` must belong to an access policy with the **`adaptive-logs:admin`** scope.

If successful, the server returns a JSON object including the `id` of the newly created exemption.

#### List exemptions

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

```bash
curl -u "$TENANT:$TOKEN" "$URL/adaptive-logs/exemptions"
```

`TOKEN` must belong to an access policy with the **`adaptive-logs:admin`** scope.

#### Get an exemption

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

```bash
curl -u "$TENANT:$TOKEN" "$URL/adaptive-logs/exemptions/<exemption_id>"
```

`TOKEN` must belong to an access policy with the **`adaptive-logs:admin`** scope.

The `exemption_id` is the identifier of the exemption to fetch, as returned by the server when creating the exemption.

#### Update an exemption

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

```bash
curl -u "$TENANT:$TOKEN" --request PUT --data @exemption.json "$URL/adaptive-logs/exemptions/<exemption_id>"
```

`TOKEN` must belong to an access policy with the **`adaptive-logs:admin`** scope.

The `exemption_id` is the identifier of the exemption to update, as returned by the server when creating the exemption.

#### Delete an exemption

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

```bash
curl -u "$TENANT:$TOKEN" --request DELETE "$URL/adaptive-logs/exemptions/<exemption_id>"
```

`TOKEN` must belong to an access policy with the **`adaptive-logs:admin`** scope.

The `exemption_id` is the identifier of the exemption to delete, as returned by the server when creating the exemption.

### Drop rules

Drop rules let you define custom rules that drop a percentage of log lines matching specific criteria. Unlike recommendations, which are system-generated, drop rules are user-defined and give you fine-grained control over which logs are dropped.

Each drop rule has the following format:

Expand table

| Field name              | Type       | Description                                                                  |
|-------------------------|------------|------------------------------------------------------------------------------|
| `id`                    | identifier | Unique identifier of the drop rule (set by the server).                      |
| `segment_id`            | string     | The segment this rule belongs to. Use `__global__` for tenant-wide rules.    |
| `name`                  | string     | A human-readable name for the drop rule.                                     |
| `version`               | integer    | The version of the drop rule, used for optimistic concurrency control.       |
| `disabled`              | boolean    | Whether the drop rule is currently disabled.                                 |
| `expires_at` (optional) | timestamp  | When this drop rule expires. If not set, the drop rule is permanent.         |
| `created_at`            | timestamp  | When the drop rule was created (set by the server).                          |
| `updated_at`            | timestamp  | When the drop rule was last updated (set by the server).                     |
| `body`                  | object     | The rule definition, containing the fields described in the following table. |

The `body` object has the following fields:

Expand table

| Field name                     | Type      | Description                                                                         |
|--------------------------------|-----------|-------------------------------------------------------------------------------------|
| `stream_selector`              | string    | A LogQL stream selector that defines which log streams the rule applies to.         |
| `drop_rate`                    | number    | The percentage of matching log lines to drop (0 to 100).                            |
| `levels` (optional)            | string\[] | Log levels to match (for example, `["info", "debug"]`). If empty, all levels match. |
| `log_line_contains` (optional) | string\[] | Strings that must appear in the log line for the rule to apply.                     |

Below is an example of a drop rule:

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

```json
{
  "segment_id": "__global__",
  "name": "Drop noisy health checks",
  "version": 1,
  "disabled": false,
  "body": {
    "stream_selector": "{service_name=\"api-gateway\"}",
    "drop_rate": 90,
    "levels": ["info", "debug"],
    "log_line_contains": ["healthcheck"]
  }
}
```

#### Create a drop rule

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

```bash
curl -u "$TENANT:$TOKEN" --request POST --data @drop-rule.json "$URL/adaptive-logs/drop-rules"
```

`TOKEN` must belong to an access policy with the **`adaptive-logs:admin`** scope.

If successful, the server returns a JSON object including the `id` of the newly created drop rule.

#### List drop rules

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

```bash
curl -u "$TENANT:$TOKEN" "$URL/adaptive-logs/drop-rules"
```

`TOKEN` must belong to an access policy with the **`adaptive-logs:admin`** scope.

You can filter results with the following query parameters:

Expand table

| Parameter           | Description                                                 |
|---------------------|-------------------------------------------------------------|
| `segment_id`        | Filter by segment. Use `__global__` for tenant-wide rules.  |
| `expiration_filter` | Filter by expiration status: `all`, `active`, or `expired`. |

#### Get a drop rule

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

```bash
curl -u "$TENANT:$TOKEN" "$URL/adaptive-logs/drop-rules/<drop_rule_id>"
```

`TOKEN` must belong to an access policy with the **`adaptive-logs:admin`** scope.

The `drop_rule_id` is the identifier of the drop rule to fetch, as returned by the server when creating the drop rule.

#### Update a drop rule

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

```bash
curl -u "$TENANT:$TOKEN" --request PUT --data @drop-rule.json "$URL/adaptive-logs/drop-rules/<drop_rule_id>"
```

`TOKEN` must belong to an access policy with the **`adaptive-logs:admin`** scope.

The `drop_rule_id` is the identifier of the drop rule to update, as returned by the server when creating the drop rule.

#### Delete a drop rule

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

```bash
curl -u "$TENANT:$TOKEN" --request DELETE "$URL/adaptive-logs/drop-rules/<drop_rule_id>"
```

`TOKEN` must belong to an access policy with the **`adaptive-logs:admin`** scope.

The `drop_rule_id` is the identifier of the drop rule to delete, as returned by the server when creating the drop rule.

### Segments

Segments let you organize log streams into groups based on a shared label, so you can manage Adaptive Logs recommendations on a per-team or per-service basis.

Each segment has the following format:

Expand table

| Field name | Type       | Description                                                                    |
|------------|------------|--------------------------------------------------------------------------------|
| `id`       | identifier | Unique identifier of the segment (set by the server).                          |
| `name`     | string     | A human-readable name for the segment.                                         |
| `selector` | string     | A LogQL stream selector that defines which log streams belong to this segment. |

> Note
> 
> All segments must reference the same label name. Only equality matchers (for example, `{team="billing"}`) or multi-literal regular expression matchers (for example, `{team=~"(alerting|alerting-dev)"}`) are allowed.

Below is an example of a segment:

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

```json
{
  "name": "Billing team",
  "selector": "{team=\"billing\"}"
}
```

#### Create a segment

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

```bash
curl -u "$TENANT:$TOKEN" --request POST --data @segment.json "$URL/adaptive-logs/segment"
```

`TOKEN` must belong to an access policy with the **`adaptive-logs:admin`** scope.

If successful, the server returns a JSON object including the `id` of the newly created segment.

#### List segments

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

```bash
curl -u "$TENANT:$TOKEN" "$URL/adaptive-logs/segments"
```

`TOKEN` must belong to an access policy with the **`adaptive-logs:admin`** scope.

#### Get a segment

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

```bash
curl -u "$TENANT:$TOKEN" "$URL/adaptive-logs/segment?segment=<segment_id>"
```

`TOKEN` must belong to an access policy with the **`adaptive-logs:admin`** scope.

The `segment_id` is the identifier of the segment to fetch, as returned by the server when creating the segment.

#### Update a segment

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

```bash
curl -u "$TENANT:$TOKEN" --request PUT --data @segment.json "$URL/adaptive-logs/segment?segment=<segment_id>"
```

`TOKEN` must belong to an access policy with the **`adaptive-logs:admin`** scope.

The `segment_id` is the identifier of the segment to update, as returned by the server when creating the segment.

#### Delete a segment

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

```bash
curl -u "$TENANT:$TOKEN" --request DELETE "$URL/adaptive-logs/segment?segment=<segment_id>"
```

`TOKEN` must belong to an access policy with the **`adaptive-logs:admin`** scope.

The `segment_id` is the identifier of the segment to delete, as returned by the server when creating the segment.