--- title: Metric API limits and restricted attributes source: https://docs.newrelic.com/docs/data-apis/ingest-apis/metric-api/metric-api-limits-restricted-attributes --- This document describes data requirements for the [Metric API](https://docs.newrelic.com/docs/new-relic-metric-api), including: - Maximum limits - Restricted attributes - Restricted metric values ## Maximum limits [#requirements] The following default limits apply for all Metric data: | Condition | Limit | | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Age range for timestamp values | Metrics reported with a timestamp older than 48 hours ago or newer than 24 hours from the time they are reported are dropped. | | Max unique time series (cardinality) per account per day | 1-15 million [(learn more)](#additional-considerations) A time series is a single, unique combination of a metric name and any attributes. | | Max unique time series (cardinality) per metric name per day | 100k | | Max payloads per minute | 100k [(learn more)](#additional-considerations) | | Max attributes per metric | 150 | | Max metric attribute name length | 255 characters | | Max characters for an attribute key | 255 characters | | Max metric attribute value length | 4096 characters | | Allowed HTTP protocols | HTTPS only | | Numerical long values falling outside minimum or maximum Java long values | Numerical long values that fall outside of the minimum or maximum Java long value will be rejected. - If the number is in the common block, then the entire block will be dropped. - If the number is in a metric data point, then the metric data point it resides in will be dropped. | | Numerical double values falling outside minimum or maximum Java double values | Numeric double values that fall outside of a the minimum or maximum Java double value will be rejected. - If the number is in the common block, then the entire block will be dropped. - If the number is in a metric data point, then the metric data point it resides in will be dropped. | | Numerical double values that require rounding to convert to a double-precision floating-point number. | Numeric double values that require rounding to convert to a double-precision floating-point number will be rejected. An example of this is `1.12345678901234567E18`. A double can contain a value this large but it does not have enough precision to represent it accurately (it would have to be rounded to `1.12345678901234573E18`). - If the number is in the common block, then the entire block will be dropped. - If the number is in a metric data point, then the metric data point it resides in will be dropped. | | Payload size | Total maximum size or length: **1MB (10^6 bytes) maximum per POST**. We highly recommend using compression. | | Payload format | The payload must encoded as **UTF-8**. | | Attribute naming syntax | Attribute names can be a combination of alphanumeric characters, colons (`:`), periods (`.`), and underscores (`_`). | The following default limits apply only to data collected via the Prometheus Remote Write integration: | Condition | Limit | | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Max unique Count and Summary time series (cardinality) per account per 5 minute interval | 1-15 million [(learn more)](#additional-considerations) A time series is a single, unique combination of a metric name and any attributes. Time series received above this limit are dropped. This limit is enforced prior to and in addition to standard metric limits. | ### Additional account conditions [#additional-considerations] Metric API limits apply at the individual account level. The default cardinality limit ranges from 3M for organizations on our [Free edition](https://newrelic.com/pricing), up to 10.2M for some paying organizations. To understand your organization's limits, see the [Limits UI](https://docs.newrelic.com/docs/data-apis/manage-data/view-system-limits). Cardinality can be increased to 15M on request for paying organizations. Max payloads per minute can be adjusted above 100k on a case-by-case basis. To request changes to your metric rate limits, contact your New Relic account representative, or visit our [Support portal](http://support.newrelic.com/). ## Rate limit incidents [#rate-limit-incidents] This section describes how the Metric API behaves when you exceed the rate limits, and how to respond if limits are exceeded. **Max unique time series per account per day** A time series is a single, unique combination of a metric name and any attributes assigned to that metric. For example, if a `CPU utilization` metric with a single attribute `hostname` is sent from ten different hosts, this equals ten distinct values for the `hostname` attribute and ten unique metric time series. If the per-account, per-day unique metric time series (cardinality) limit is exceeded during a 24 hour period, the endpoint will continue to receive and store raw metric data. However, New Relic will stop creating additional aggregate rollups (1 minute, 5 minutes, etc.) for the remainder of the 24 hour period. (These rollups are used used by default to query time windows longer than 60 minutes.) You can continue to query your data when such an incident occurs by specifying a 60 minute or shorter time window or specifying the RAW keyword (for more on that, see [High cardinality metrics](https://docs.newrelic.com/docs/data-apis/ingest-apis/metric-api/NRQL-high-cardinality-metrics)). This can be helpful in identifying potential causes for the incident. **Max unique time series per metric name per day** A time series is a single, unique combination of a metric name and any attributes assigned to that metric. For example, if a `CPU utilization` metric with a single attribute `hostname` is sent from ten different hosts, this equals ten distinct values for the `hostname` attribute and ten unique metric time series. If the per-metric name, per-day unique metric time series (cardinality) limit is exceeded during a 24 hour period, the endpoint will continue to receive and store raw metric data. However, New Relic will stop creating additional aggregate rollups (1 minute, 5 minutes, etc.) for the remainder of the 24 hour period. (These rollups are used used by default to query time windows longer than 60 minutes.) You can continue to query your data when such an incident occurs by specifying a 60 minute or shorter time window or specifying the RAW keyword (for more on that, see [High cardinality metrics](https://docs.newrelic.com/docs/data-apis/ingest-apis/metric-api/NRQL-high-cardinality-metrics)). This can be helpful in identifying potential causes for the incident. **Max payloads per minute** If you make more than 100k POST requests to the Metric API endpoint within a minute, the endpoint will return a `429` response for the remainder of the minute. The response will include a `Retry-After` header indicating how long to wait in seconds before resubmitting or sending new data. In general, if you reach this limit, consider creating larger payloads. To do this, combine more data points into each request to reduce the number of POSTs that are necessary. If this is not an option, you can request a rate limit increase by contacting your New Relic account representative or visiting our [Support portal](http://support.newrelic.com/). ## Restricted attributes [#send-metric-data] These attributes are restricted by the New Relic platform. Any values submitted with these keys in the attributes section of a metric data point will cause the data point to be dropped, or the value to be omitted or overwritten: | Attribute | Description | | ----------------- | ------------------------------------------------------------------------------------------------------- | | `newrelic.source` | This resets to the value `metricAPI`. | | `metricName` | This resets to the `name` value passed into each data point. This allows `name` to be an attribute key. | | `endTimestamp` | `timestamp` and `interval.ms` will be converted to an `endTimestamp` for the data point. | These attributes are used internally to identify entities. Any values submitted with these keys in the attributes section of a metric data point may cause undefined behavior such as missing entities in the UI or telemetry not associating with the expected entities. For more information please refer to [Entity synthesis](https://docs.newrelic.com/docs/new-relic-one/use-new-relic-one/core-concepts/what-entity-new-relic/#entity-synthesis): | Attribute | Description | | ------------- | ----------------------------------------------------------------------------------------- | | `entity.guid` | Unique identifier assigned to an entity by New Relic. | | `entity.name` | Human-readable name of an entity, often used to identify an entity in the UI. | | `entity.type` | Used to differentiate between different types of entities, like hosts, applications, etc. | Additional restrictions include: | Restriction | Comments | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Metric and attribute names | You cannot pass the same value for metric name and attribute name. In the following example, the metric is invalid because the metric is named `service.errors.all` and there is an attribute `service.errors.all`. **Example: Metric value used as an attribute (invalid)** ````json [ { "metrics": [ { "name": "service.errors.all", "type": "count", "value": 15, "timestamp": 1531414060739, "interval.ms": 10000, "attributes": { "service.response.statuscode": "400", "service.errors.all": "test", "service.name": "foo" } } ] } ] ``` ```` | | Reserved words | Avoid using [reserved words](https://docs.newrelic.com/docs/data-apis/custom-data/custom-events/data-requirements-limits-custom-event-data/#reserved-words), such as `accountId`, `appId`, and `eventType`. You should also avoid using NRQL syntax terms unless you backtick (``` `` ```) them. | | Keys within metric JSON | All keys used within the metric JSON cannot be attribute keys. This includes `interval.ms`, `timestamp`, `value`, `common`, `min`, `max`, `count`, `sum`, and `metrics`. **Exception:** You can use `name` as an attribute key. | ## Restricted metric values [#restricted-metric-values] Any metric data submitted to the Metric API with a `value` equal to `NaN` (not a number), `positive infinity`, or `negative infinity` will be dropped. Non-finite values may cause [`NrIntegrationError`](https://docs.newrelic.com/docs/data-apis/ingest-apis/metric-api/troubleshoot-nrintegrationerror-events/) events to be emitted.