# TCO Optimizer HTTP API

Copy as Markdown[Open in ChatGPT](https://chatgpt.com/?q=Read%20https%3A%2F%2Fdocs-docusaurus.kinsta.page%2Fdeveloper-portal%2Fapis%2Ftco-controls%2Ftco-optimizer-http-api.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)[Open in Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Fdocs-docusaurus.kinsta.page%2Fdeveloper-portal%2Fapis%2Ftco-controls%2Ftco-optimizer-http-api.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)

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://docs-docusaurus.kinsta.page/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://docs-docusaurus.kinsta.page/user-guides/account-management/tco-optimizer/.md#policies-and-filters), used both for spans and logs.

## Base URL[​](#base-url "Direct link to Base URL")

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

## Header[​](#header "Direct link to Header")

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

### API key[​](#api-key "Direct link to API key")

To use the TCO Optimizer API you need to [create](https://docs-docusaurus.kinsta.page/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[​](#usage "Direct link to Usage")

### Severity options[​](#severity-options "Direct link to Severity options")

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

### Priority options[​](#priority-options "Direct link to Priority options")

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

## TCO override[​](#tco-override "Direct link to 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[​](#impact "Direct link to 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[​](#prevention "Direct link to 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[​](#supported-endpoints "Direct link to Supported endpoints")

### Get all policy overrides[​](#get-all-policy-overrides "Direct link to 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.{cx.endpoints.domain\_only}/api/v1/external/tco/overrides](https://api.%7Bcx.endpoints.domain_only%7D/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-single-policy-override-by-id "Direct link to Get single policy override by ID")

**GET** /overrides/{id}

**Route example:** [https://api.{cx.endpoints.domain\_only}/api/v1/external/tco/overrides/972f6b98-343c-11ee-ac29-061115d0c307](https://api.%7Bcx.endpoints.domain_only%7D/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[​](#create-single-policy-override "Direct link to Create single policy override")

**POST** /overrides

**Route example:** [https://api.{cx.endpoints.domain\_only}/api/v1/external/tco/overrides](https://api.%7Bcx.endpoints.domain_only%7D/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[​](#create-multiple-policy-overrides "Direct link to Create multiple policy overrides")

**POST** /overrides/bulk

**Route example:** [https://api.{cx.endpoints.domain\_only}/api/v1/external/tco/overrides/bulk](https://api.%7Bcx.endpoints.domain_only%7D/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[​](#update-multiple-policy-overrides "Direct link to Update multiple policy overrides")

**PUT** /overrides/bulk

**Route example:** [https://api.{cx.endpoints.domain\_only}/api/v1/external/tco/overrides/bulk](https://api.%7Bcx.endpoints.domain_only%7D/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-single-policy-override "Direct link to Delete single policy override")

**DELETE** /overrides/{id}

**Route example:** [https://api.{cx.endpoints.domain\_only}/api/v1/external/tco/overrides/2c53d05f-343d-11ee-ac29-061115d0c307](https://api.%7Bcx.endpoints.domain_only%7D/api/v1/external/tco/overrides/2c53d05f-343d-11ee-ac29-061115d0c307)

**Response example:**

```
{

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

}
```

### Delete multiple policy overrides[​](#delete-multiple-policy-overrides "Direct link to Delete multiple policy overrides")

**DELETE** /overrides/bulk

**Route example:** [https://api.{cx.endpoints.domain\_only}/api/v1/external/tco/overrides/bulk](https://api.%7Bcx.endpoints.domain_only%7D/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-all-tco-policies "Direct link to Get all TCO policies")

**GET** /policies

**Route example:** [https://api.{cx.endpoints.domain\_only}/api/v1/external/tco/policies](https://api.%7Bcx.endpoints.domain_only%7D/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[​](#create-tco-policy "Direct link to Create TCO policy")

**POST** /policies

**Route example:** [https://api.{cx.endpoints.domain\_only}/api/v1/external/tco/policies](https://api.%7Bcx.endpoints.domain_only%7D/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[​](#reorder-policies "Direct link to 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.{cx.endpoints.domain\_only}/api/v1/external/tco/policies/reorder](https://api.%7Bcx.endpoints.domain_only%7D/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-tco-policy "Direct link to Delete TCO policy")

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

**Route example:** [https://api.{cx.endpoints.domain\_only}/api/v1/external/tco/policies/90503f12-c291-4bbf-b437-5022f39d258d](https://api.%7Bcx.endpoints.domain_only%7D/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[​](#additional-resources "Direct link to Additional resources")

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