--- title: Trace API general requirements and limits source: https://docs.newrelic.com/docs/distributed-tracing/trace-api/trace-api-general-requirements-limits --- Information about [Trace API](https://docs.newrelic.com/docs/apm/distributed-tracing/trace-api/introduction-new-relic-trace-api) data requirements, including: - Data specifications and max limits - Required metadata (headers, query parameters) - Response validation details This document applies to the Trace API overall. For rules regarding specific data formats, see: - [New Relic-format trace data](https://docs.newrelic.com/docs/apm/distributed-tracing/trace-api/report-new-relic-format-traces-trace-api) - [Zipkin-format trace data](https://docs.newrelic.com/docs/apm/distributed-tracing/trace-api/report-zipkin-format-traces-trace-api) ## Endpoints [#requirements] All trace data is sent via HTTPS POST to a Trace API endpoint. We have a few endpoints, depending on your setup: - Default Trace API endpoint: `https://trace-api.newrelic.com/trace/v1` - EU data center: `https://trace-api.eu.newrelic.com/trace/v1` (see other [EU endpoints](https://docs.newrelic.com/docs/using-new-relic/welcome-new-relic/getting-started/introduction-eu-region-data-center#endpoints)). - JP data center: `https://trace-api.jp.nr-data.net/trace/v1` (see other [JP endpoints](https://docs.newrelic.com/docs/accounts/accounts-billing/account-setup/choose-your-data-center/#jp-endpoints)). - [Infinite Tracing](https://docs.newrelic.com/docs/understand-dependencies/distributed-tracing/infinite-tracing/introduction-infinite-tracing): When you complete the [Trace observer setup](https://docs.newrelic.com/docs/understand-dependencies/distributed-tracing/infinite-tracing/set-trace-observer), you get a custom YOUR_TRACE_OBSERVER_URL value to use as an endpoint. If you're using an integration that uses the Trace API (for example, [the Kamon reporter](https://docs.newrelic.com/docs/more-integrations/open-source-telemetry-integrations/kamon/kamon-reporter/#install)), you must configure that integration with that endpoint. You will also want to adjust the [sampling of your tracing service](https://docs.newrelic.com/docs/understand-dependencies/distributed-tracing/get-started/how-new-relic-distributed-tracing-works#tail-based) to send us 100% of spans. - FedRAMP: See [FedRAMP endpoints](https://docs.newrelic.com/docs/security/security-privacy/compliance/fedramp-compliant-endpoints/#trace-api). ## Data formats [#data-formats] Currently, the Trace API accepts two types of data formats: - [`zipkin`](https://docs.newrelic.com/docs/apm/distributed-tracing/trace-api/report-zipkin-format-traces-trace-api): For reporting Zipkin trace data. Zipkin data must be [Zipkin JSON v2](https://zipkin.io/zipkin-api/#/default/post_spans). - [`newrelic`](https://docs.newrelic.com/docs/apm/distributed-tracing/trace-api/report-new-relic-format-traces-trace-api): For reporting all other trace data. ## Restricted attributes [#restricted-attributes] The attributes in the table below are restricted in the `newrelic`-format JSON (in the `attributes` block) and in the [`zipkin`](https://docs.newrelic.com/docs/apm/distributed-tracing/trace-api/report-zipkin-format-traces-trace-api)-format JSON (in the `tags` block). **Any values with these keys will be omitted**: | Restricted attribute | Description | | --------------------- | ----------------------------------------------------------------------------------------------------- | | `entityGuid` _string_ | Unique identifier for the entity that created this span. Generated from `service.name`, if available. | | `guid` _string_ | Used for backwards compatibility with data from APM agents. | The attributes in the table below 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): | Restricted attribute | description | | ---------------------- | ----------------------------------------------------------------------------------------- | | `entity.guid` _string_ | Unique identifier for the entity associated with this span. | | `entity.name` _string_ | Human-readable name of an entity, often used to identify an entity in the UI. | | `entity.type` _string_ | Used to differentiate between different types of entities, like hosts, applications, etc. | ## Request metadata (headers and query parameters) [#headers-query-parameters] The following table shows the required request metadata for all trace data formats. This metadata can be sent as HTTP headers on an ingest request or, in some cases, provided as query parameters, which may be required for tracing frameworks that don't allow header modification. > #### ⚠️ IMPORTANT > > Security note: We suggest using headers because query parameters are present in the URL and may be logged before being encrypted and received by New Relic. All data sent as query parameters must be URL-safe. | Header | Query param? | Details | | --------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Content-Type` | No | **Required.** Must be `application/json`. | | `Content-Length` | No | **Required.** The length of the request body in octets (8-bit bytes) unless sent with chunked encoding. This header is generally set by default by the underlying HTTP client sending the data and in most cases should not require any additional effort by the end user. | | `Api-Key` | Yes (case-sensitive) | **Required.** The Trace API requires a license key. If this is provided as both a header and a query parameter, the values must match. | | `Content-Encoding` | No | **Required if compressed payload.** The value must be `gzip`. | | `Data-Format` | Yes | **Required for `zipkin`**. Optional for `newrelic`. If present, [`Data-Format-Version`](#data-format-version) must also be present. | | `Data-Format-Version` | Yes | **Required for `zipkin`**. If present, `Data-Format` must also be present. There are only two possible pairings for these values: - If `Data-Format` is `zipkin`, `Data-Format-Version` must be `2`. - If `Data-Format` is `newrelic`, `Data-Format-Version` must be `1`. | | `x-request-id` | No | **Optional - Reserved for future use.** The value must be a valid `UUID4`. The value is expected to be unique for each request. | ## Response validation A response for successfully sending trace data will include a `requestId`. For example: ```json {"requestId":"c1bb62fc-001a-b000-0000-016bb152e1bb"} ``` There are two ways success/errors are signaled: - **HTTP status code** (synchronous). Authentication and request errors will be signaled via HTTP status code. **See HTTP status codes** | Code | Meaning | | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 202 | Data accepted. This means that you've passed preliminary checks, but is not a guarantee that the data has been successfully parsed and indexed as part of a distributed trace. | | 400 | The structure of the request was invalid. Errors with query parameters, etc. | | 403 | Authentication error. May occur with an invalid license key or if you lack necessary entitlement to use the Trace API. | | 404 | The request path is incorrect. | | 405 | For any request method other than POST. | | 408 | The request took too long to reach the endpoint. | | 411 | The Content-Length header wasn’t included. | | 413 | The payload was too big. | | 414 | The request URI was too long. | | 415 | The Content-Type or Content-Encoding was invalid. | | 429 | The request rate quota has been exceeded. | | 431 | The request headers are too long. | | 5xx | There was a server error (please retry). | - `NrIntegrationError` events (asynchronous). Errors with the JSON payload or other semantic errors are asynchronously signaled via [`NrIntegrationError` events](https://docs.newrelic.com/docs/telemetry-data-platform/manage-data/nrintegrationerror) that are stored in the account whose license key is associated with the request. For all errors of this type, the attribute `newRelicFeature` will be `Distributed Tracing` and `requestId` will be the `requestId` from the endpoint response. If you receive a `202` response and don't see an `NrIntegrationError` event, your data should be visible in our global [distributed tracing UI](https://one.newrelic.com/launcher/distributed-tracing-nerdlets.distributed-tracing#launcher=eyJ0aW1lUmFuZ2UiOnsiYmVnaW5fdGltZSI6bnVsbCwiZW5kX3RpbWUiOm51bGwsImR1cmF0aW9uIjoxODAwMDAwfX0=&pane=eyJuZXJkbGV0SWQiOiJkaXN0cmlidXRlZC10cmFjaW5nLW5lcmRsZXRzLmRpc3RyaWJ1dGVkLXRyYWNpbmctbGF1bmNoZXIiLCJzb3J0SW5kZXgiOjAsInNvcnREaXJlY3Rpb24iOiJERVNDIn0=) in about a minute. You should be able to find the trace using a standard [trace search](https://docs.newrelic.com/docs/apm/distributed-tracing/ui-data/additional-distributed-tracing-features-new-relic-one#find-data) like: ``` traceId = TRACE_ID_SENT ``` ## Data limits [#data-limits] For trace-related limits, see [How distributed tracing works](https://docs.newrelic.com/docs/distributed-tracing/concepts/how-new-relic-distributed-tracing-works/#limits).