---
title: TCO Optimizer HTTP API
description: Use the TCO Optimizer HTTP API to define, query, and manage your TCO policy overrides, used exclusively for logs.
url: https://coralogix.com/docs/developer-portal/apis/tco-controls/tco-optimizer-http-api/
product: dataengine
feature: TCO Optimizer
feature_id: tco-optimizer
feature_identifier: dataengine/tco-optimizer
last_updated: '2026-11-11'
---

# TCO Optimizer HTTP API

This tutorial demonstrates using the TCO Optimizer HTTP API to define, query, and manage your TCO policy overrides for logs.

Go to [this page](https://coralogix.com/docs/developer-portal/apis/tco-controls/tco-tracing-policy-grpc-api.md) to learn how to use the **TCO Tracing gPRC API** to define, query, and manage your [TCO policy criteria](https://coralogix.com/docs/user-guides/account-management/tco-optimizer/create-and-manage-policies.md#policies-and-filters), used both for spans and logs.

## Base URL

Choose the <!-- -->https\://api./api/v1/external/tco<!-- --> endpoint that corresponds to your Coralogix [domain](https://coralogix.com/docs/user-guides/account-management/account-settings/coralogix-domain.md) using the domain selector at the top of the page.

## Header

| Key           | Value                 |
| ------------- | --------------------- |
| Content-Type  | application/json      |
| Authorization | Bearer `<cx_api_key>` |

### API key

To use the TCO Optimizer API you need to [create](https://coralogix.com/docs/user-guides/account-management/api-keys/api-keys.md) a personal or team API key. It’s recommended to use permission presets, as they are automatically updated with all relevant permissions. Alternatively, you can manually add individual permissions.

| Preset      | Action                                                                                                                                                                                 | Description                                                                                                                                                                          |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| TCOPolicies | `LOGS.TCO:READPOLICIES`<br />`LOGS.TCO:UPDATEPOLICIES`<br />`SPANS.TCO:READPOLICIES`<br />`SPANS.TCO:UPDATEPOLICIES`<br />`METRICS.TCO:READPOLICIES`<br />`METRICS.TCO:UPDATEPOLICIES` | View Logs TCO Policies<br />Manage Logs TCO Policies<br />View Tracing TCO Policies<br />Manage Tracing TCO Policies<br />View Metrics TCO Policies<br />Manage Metrics TCO Policies |

## Usage

### Severity options

| Name     | Value |
| -------- | ----- |
| debug    | 1     |
| verbose  | 2     |
| info     | 3     |
| warning  | 4     |
| error    | 5     |
| critical | 6     |

### Priority options

| Name   | Value  |
| ------ | ------ |
| block  | block  |
| low    | low    |
| medium | medium |
| high   | high   |

## TCO override

Configuring a TCO override replaces the TCO policy for the specified application-subsystem-severity combination, including any associated Archive Retention Tags. In these cases, the Archive Retention Tag is overridden and reverts to the `default` tag.

### Impact

This behavior directly impacts S3 lifecycle policies that depend on retention tags. If the tag is overridden to the `default`, lifecycle policies associated with specific tags, like 'Revenue,' may not be applied as intended, potentially resulting in unintended data deletion.

### Prevention

If you manage S3 Lifecycle Policies based on Archive Retention Tags, review and adjust overrides to prevent unintended data deletion.

**Example**

* TCO override is not in use: Retention Tag = `revenue`, Lifecycle Policy transitions data to Glacier after 30 days and deletes it from Glacier after 1 year.

* TCO override is in use: Retention Tag = `default`, Lifecycle Policy expires data after 60 days (if set to `default`).

## Supported endpoints

### Get all policy overrides

Note

This endpoint returns only policy overrides. If a policy is applied but not explicitly overridden, it will not appear in the response. If no overrides exist, the response will be empty.

**GET** /overrides

**Route example:** `https://api.eu2.coralogix.com/api/v1/external/tco/overrides`

**Response example:**

```
[

    {

        "id": "dd361b69-89c7-11ec-a5ad-0616c20b31c7",

        "name": "default|recommendationservice|INFO",

        "priority": "high",

        "severity": 3,

        "applicationName": "default",

        "subsystemName": "recommendationservice"

    },

    {

        "id": "61d551af-8f96-11ec-8bfb-02dd69f0920d",

        "name": "default|checkoutservice|DEBUG",

        "priority": "high",

        "severity": 1,

        "applicationName": "default",

        "subsystemName": "checkoutservice"

    }

]
```

### Get single policy override by ID

**GET** /overrides/{id}

**Route example:** `https://api.eu2.coralogix.com/api/v1/external/tco/overrides/972f6b98-343c-11ee-ac29-061115d0c307`

**Response example:**

```
{

    "id": "dd361b69-89c7-11ec-a5ad-0616c20b31c7",

    "name": "default|recommendationservice|INFO",

    "priority": "high",

    "severity": 3,

    "applicationName": "default",

    "subsystemName": "recommendationservice"

}
```

### Create single policy override

**POST** /overrides

**Route example:** `https://api.eu2.coralogix.com/api/v1/external/tco/overrides`

**Request example:**

```
{

    "priority": "high",

    "severity": 3,

    "applicationName": "default",

    "subsystemName": "blablabla123"

}
```

**Response example**:

```
{

    "priority": "high",

    "severity": 3,

    "applicationName": "default",

    "subsystemName": "blablabla123",

    "id": "972f6b98-343c-11ee-ac29-061115d0c307"

}
```

### Create multiple policy overrides

**POST** /overrides/bulk

**Route example:** `https://api.eu2.coralogix.com/api/v1/external/tco/overrides/bulk`

**Request example:**

```
[

    {

        "priority": "high",

        "severity": 3,

        "applicationName": "default",

        "subsystemName": "blablabla1234"

    },

    {

        "priority": "high",

        "severity": 3,

        "applicationName": "default",

        "subsystemName": "blablabla12345"

    }

]
```

**Response example**:

```
[

    {

        "status": 200,

        "override": {

            "priority": "high",

            "severity": 3,

            "applicationName": "default",

            "subsystemName": "blablabla1234",

            "id": "2c42a7aa-343d-11ee-ac29-061115d0c307"

        }

    },

    {

        "status": 200,

        "override": {

            "priority": "high",

            "severity": 3,

            "applicationName": "default",

            "subsystemName": "blablabla12345",

            "id": "2c53d05f-343d-11ee-ac29-061115d0c307"

        }

    }

]
```

### Update multiple policy overrides

**PUT** /overrides/bulk

**Route example:** `https://api.eu2.coralogix.com/api/v1/external/tco/overrides/bulk`

**Request example:**

```
[

    {

        "id": "2c42a7aa-343d-11ee-ac29-061115d0c307",

        "name": "default|blablabla1234|INFO",

        "priority": "high",

        "severity": 3,

        "applicationName": "default",

        "subsystemName": "blablabla1234"

    },

    {

        "id": "2c53d05f-343d-11ee-ac29-061115d0c307",

        "name": "default|blablabla12345|INFO",

        "priority": "high",

        "severity": 3,

        "applicationName": "default",

        "subsystemName": "blablabla12345"

    }

]
```

**Response example**:

```
[

    {

        "status": 200,

        "override": {

            "name": "default|blablabla1234|INFO",

            "priority": "high",

            "severity": 3,

            "applicationName": "default",

            "subsystemName": "blablabla1234",

            "id": "2c42a7aa-343d-11ee-ac29-061115d0c307"

        }

    },

    {

        "status": 200,

        "override": {

            "name": "default|blablabla12345|INFO",

            "priority": "high",

            "severity": 3,

            "applicationName": "default",

            "subsystemName": "blablabla12345",

            "id": "2c53d05f-343d-11ee-ac29-061115d0c307"

        }

    }

]
```

### Delete single policy override

**DELETE** /overrides/{id}

**Route example:** `https://api.eu2.coralogix.com/api/v1/external/tco/overrides/2c53d05f-343d-11ee-ac29-061115d0c307`

**Response example:**

```
{

    "id": "2c53d05f-343d-11ee-ac29-061115d0c307"

}
```

### Delete multiple policy overrides

**DELETE** /overrides/bulk

**Route example:** `https://api.eu2.coralogix.com/api/v1/external/tco/overrides/bulk`

**Request example:**

```
[

    {

        "id": "2c42a7aa-343d-11ee-ac29-061115d0c307"

    }

]
```

**Response example**:

```
[

    {

        "status": 200,

        "override": {

            "id": "2c42a7aa-343d-11ee-ac29-061115d0c307"

        }

    }

]
```

### Get all TCO policies

**GET** /policies

**Route example:** `https://api.eu2.coralogix.com/api/v1/external/tco/policies`

**Request example:**

```
curl --location 'https://api.eu2.coralogix.com/api/v1/external/tco/policies' \

--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
```

### Create TCO policy

**POST** /policies

**Route example:** `https://api.eu2.coralogix.com/api/v1/external/tco/policies`

**Request example:**

```
curl --location 'https://api.eu2.coralogix.com/api/v1/external/tco/policies' \

--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \

--header 'Content-Type: application/json' \

--data '{

    "name": "Policy block subsystem",

    "priority": "block",

    "severities": [],

    "applicationName": {},

    "subsystemName": {

        "type": "Is",

        "rule": [

            "system_logs",

            "lambda_logs"

        ]

    }

}'
```

### Reorder policies

Sets the order of policies in the provided order. The list must contain the list of all the policies IDs in the expected new order.

**POST** /policies/reorder

**Route example:** `https://api.eu2.coralogix.com/api/v1/external/tco/policies/reorder`

**Request example:**

```
curl --location --request PUT 'https://api.eu2.coralogix.com/api/v1/external/tco/policies/reorder' \

--header 'Content-Type: application/json' \

--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \

--data '[

    "eed91808-1094-4d07-adab-17855b449888",

    "95cfa816-354a-412c-80f5-378ce33a4454"

]'
```

### Delete TCO policy

**DELETE** /policies/{tco\_policy\_id}

**Route example:** `https://api.eu2.coralogix.com/api/v1/external/tco/policies/90503f12-c291-4bbf-b437-5022f39d258d`

**Request example:**

```
curl --location --request DELETE 'https://api.eu2.coralogix.com/api/v1/external/tco/policies/90503f12-c291-4bbf-b437-5022f39d258d' \

--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
```

## Additional resources

|                     |                                                                                                                                                                                                                       |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Documentation       | [TCO Optimizer](https://coralogix.com/docs/user-guides/account-management/tco-optimizer.md)<br />[TCO Tracing gPRC API](https://coralogix.com/docs/developer-portal/apis/tco-controls/tco-tracing-policy-grpc-api.md) |
| Coralogix Endpoints | [Coralogix Endpoints](https://coralogix.com/docs/integrations/coralogix-endpoints.md)                                                                                                                                 |