--- title: "Configure Loki settings using the API | Grafana Cloud documentation" description: "Adjust Loki settings in Grafana Cloud Logs such as retention, OTLP configuration, and line truncation using the self-serve API." --- # Configure Loki settings using the API Loki offers many settings (also known as *limits*) that can be adjusted for different use cases. In Grafana Cloud Logs, we manage them all for you, and set defaults that work for most of our users. Still there may be some settings you may need to adjust such as [retention](/docs/loki/latest/operations/storage/retention/#configuring-the-retention-period), the [OTLP label mappings](/docs/loki/latest/get-started/labels/#default-labels-for-opentelemetry), or enabling truncation of long log lines that would otherwise be dropped. You can configure these settings using the self-serve API. > Caution > > Our engineering team manually reviews all requested limits to ensure system stability and performance. > > We aim to approve the requests as soon as possible, but **the review and approval process may take up to 2 business days**. > > When using the API, the GET endpoints for the requested settings show a `pending` state while we review the request and `applied` once the request is approved and applied. ## Before you begin To configure Loki settings using the self-serve API, you need the following information: - Cloud Logs Instance URL and user ID. To find this information, refer to [Find instance endpoint](/docs/grafana-cloud/security-and-account-management/cloud-stacks/#find-instance-endpoints). - API token with logs write permissions. For more information about scopes, refer to [Grafana Cloud Access Policies](/docs/grafana-cloud/security-and-account-management/authentication-and-permissions/access-policies/). Hereafter, replace `` with your Cloud Logs Instance URL, `` for your user ID, and `` for your API key. ### Use the API #### Configure new settings > Warning > > **Configured settings cannot be removed.** After configuring a limit via this endpoint, the configured settings cannot be deleted. If you want to reset the limits to the defaults, you need to do it manually with a new `PUT` request. Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash PUT /loki/api/v1/config/limits/ Authorization: Bearer : Content-Type: application/yaml ``` Where `` is the name of the limit you want to set. The body of the request should contain the values for the limit. You can optionally pass a metadata field with an author name. Refer to the [Supported settings and restrictions](#supported-settings-and-restrictions) section for examples. #### GET configured settings Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash GET /loki/api/v1/config/limits/ Authorization: Bearer : ``` This endpoint returns: - The configured value for the limit (if any). - The status: `applied` if the changes are applied already, `pending` if the values have not been applied yet, or `pending-too-long` if the requested values have been in pending state for longer than expected. - Other metadata about the last successful `PUT` request such as the author, timestamp and request ID. #### GET applied settings Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash GET /loki/api/v1/config/limits/applied Authorization: Bearer : ``` Returns the configurable settings that Grafana Cloud Logs is applying to your tenant. Until the requested settings are applied, **this endpoint may show different values from the ones you configured**. ## Supported settings and restrictions Here is a list of the limits that can be configured using the API, along with the restrictions that apply to each. > Note > > If you need to set any of these settings but the restrictions prevent you from doing it, open a support ticket. > Note > > Our engineering team may need to override your configured settings. In case your settings are not applied within 2 business days, contact support for assistance. ### Configure retention By default, Grafana Cloud Logs has a retention of 30 days. You can increase it via the `retention_period` or `retention_stream` limits. If you need to set a retention of something less than 30 days, contact Grafana Support. - When using the API, you cannot decrease the retention below the currently configured or applied value (or 30 days by default). The UI allows retention reduction with an explicit confirmation step. - The maximum configurable retention period is 1 year. - The period must be a multiple of 30 days (for example 60d, 90d, etc.). > Note > > Note that the minimum charge is for 30 day retention, lowering it below 30 days will not further reduce your costs. Increasing the retention period beyond the minimum 30 days will increase your costs. For more information, refer to [Logs invoice](/docs/grafana-cloud/cost-management-and-billing/manage-invoices/understand-your-invoice/logs-invoice/). You can learn more about retention in the [Log retention documentation](/docs/loki/latest/operations/storage/retention/#configuring-the-retention-period). #### Configure retention using the API You cannot decrease the retention below the currently configured or applied retention through the self-service API (or 30 days by default). Here are some examples. First for configuring the global retention period: Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash curl -X PUT \ -H "Authorization: Bearer :" \ -H "Content-Type: application/yaml" \ --data-binary @retention_period.yaml \ /loki/api/v1/config/limits/retention_period ``` YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml # retention_period.yaml retention_period: 90d metadata: author: 'john@email.com' ``` And for stream retention: Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash curl -X PUT \ -H "Authorization: Bearer :" \ -H "Content-Type: application/yaml" \ --data-binary @retention_stream.yaml \ /loki/api/v1/config/limits/retention_stream ``` YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml # retention_stream.yaml retention_stream: - period: 90d selector: '{env="prod"}' - period: 60d selector: '{env="dev"}' metadata: author: 'john@email.com' ``` ### OTLP label mappings Grafana Cloud Logs configures a [default set of OpenTelemetry resource labels mapping to stream labels](/docs/loki/latest/get-started/labels/#default-labels-for-opentelemetry). If you need to modify the labels mapping, you can configure them using the API. Restrictions: - You can promote up to 30 resource attributes to stream labels (that is the attributes with `action: index_label`). - The `severity_text_as_label` field cannot be set to `true`. > Warning > > Promoting high cardinality labels may negatively affect the performance of Loki and slow down queries. Refer to the documentation for [how to estimate cardinality](/docs/loki/latest/get-started/labels/cardinality/) and [design an effective labeling strategy](/docs/loki/latest/get-started/labels/bp-labels/). #### Use the API to map labels Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash curl -X PUT \ -H "Authorization: Bearer :" \ -H "Content-Type: application/yaml" \ --data-binary @otlp_config.yaml \ /loki/api/v1/config/limits/otlp_config ``` YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml # otlp_config.yaml otlp_config: resource_attributes: attributes_config: - action: index_label attributes: [region, cluster] - action: structured_metadata attributes: [pod] - action: drop attributes: [owner] scope_attributes: - action: structured_metadata attributes: [team, experiment] - action: drop regex: 'java_jdk_*' log_attributes: - action: structured_metadata attributes: [email] - action: drop attributes: [password] metadata: author: 'john@email.com' ``` #### Move mapped resource attributes from indexed labels to structured metadata In cases where resource attributes that are part of the [default mapping](/docs/loki/latest/get-started/labels/#default-labels-for-opentelemetry) have high cardinality and should not be stored as indexed labels, but as structured metadata instead, you must use both the `drop` stage to remove them from the indexed labels **and** the `structured_metadata` stage to add them as structured metadata. A common example is the `service.instance.id` resource attribute, which tends to have relatively high cardinality. Using the API: YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml # otlp_config.yaml otlp_config: resource_attributes: attributes_config: - action: drop attributes: [service.instance.id] - action: structured_metadata attributes: [service.instance.id] ``` ### Set max line truncation By default, Grafana Cloud Logs drops all log lines that exceed the maximum log line size, 256KB. You can enable `max_line_size_truncate` ([refer to the limits configuration docs](/docs/loki/latest/configure/#limits_config)) to truncate the lines that exceed the maximum log line size instead of dropping the logs. #### Use the API to truncate lines Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash curl -X PUT \ -H "Authorization: Bearer :" \ -H "Content-Type: application/yaml" \ --data-binary @max_line_size_truncate.yaml \ /loki/api/v1/config/limits/max_line_size_truncate ``` YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml # max_line_size_truncate.yaml max_line_size_truncate: true metadata: author: 'john@email.com' ```