Correlation IDs in APIs: what they are and how to use them

A correlation ID in an API is a unique identifier created at the first point a request enters your system and then passed unchanged through every downstream call. It lets you tie together all related logs and events for that single request, which makes troubleshooting much faster. This practice is widely recommended for distributed systems and is typically implemented via an HTTP header on requests and responses (https://microsoft.github.io/code-with-engineering-playbook/observability/correlation-id/).

Why correlation IDs matter

In multi-service or microservice architectures, understanding a single user transaction across components can be difficult. A correlation ID acts as the “glue” that binds the transaction together so you can query logs across services using one token (https://microsoft.github.io/code-with-engineering-playbook/observability/correlation-id/). Some public APIs also return the correlation ID in their responses so customers and support can reference a specific call when reporting issues. For example, PayPal includes a Correlation ID in every API response to help its support locate relevant logs (https://www.paypal.com/us/cshelp/article/what-is-the-%E2%80%9Ccorrelation-id%E2%80%9D-field-in-the-api-used-for-ts1087).

How to generate and propagate a correlation ID

Where the ID comes from

Assign a correlation ID as early as possible, typically at the API gateway or first service to receive the request. If the client provides one, you can accept it; if not, generate a unique value and attach it to the request context for use by all components. Ensure every service logs the same ID and forwards it on any outbound calls (https://microsoft.github.io/code-with-engineering-playbook/observability/correlation-id/).

Header names and response behavior

Use one consistent HTTP header to carry the value. The name X-Correlation-ID is commonly used in practice and returned in responses in real-world systems, such as the example described by Salesforce Engineering (https://engineering.salesforce.com/investigate-issues-with-ease-by-adding-a-correlation-id-to-your-api-7a689413ff44/). Microsoft’s guidance also recommends adding the ID to outgoing responses where possible (https://microsoft.github.io/code-with-engineering-playbook/observability/correlation-id/).

Ship a correlation ID in your API in under a day

• Pick a single header name (e.g., X-Correlation-ID) and document it
• Generate a unique ID at ingress when the header is absent (UUID v4 works well)
• Attach the ID to the request context and include it in all request/response logs
• Propagate the same header unchanged on all downstream HTTP or message calls
• Return the ID in the API response header and note it in your API docs
• Verify proxies/gateways don’t strip or rename the header
• Add a saved search or dashboard in your log platform to filter by the ID

Correlation IDs versus distributed tracing

Correlation IDs group all events for a single request. Distributed tracing adds structure and timing by linking spans into a trace tree (trace ID and span IDs). Tracing is ideal for latency analysis and understanding parent-child call relationships. Many teams use both: a correlation ID for log searches and a trace ID for deep performance diagnosis (https://last9.io/blog/correlation-id-vs-trace-id/). Microsoft also notes that OpenTelemetry provides end-to-end context propagation, with a TraceId serving as the correlation mechanism inside a tracing system (https://microsoft.github.io/code-with-engineering-playbook/observability/correlation-id/).

Common pitfalls and quick fixes

• Regenerating the ID mid-flight breaks the chain. Ensure middleware and shared libraries preserve an existing header rather than replacing it (https://microsoft.github.io/code-with-engineering-playbook/observability/correlation-id/).
• Header inconsistency causes gaps. Standardize the header name across services and gateways. Salesforce’s example shows using x-correlation-id consistently from edge to backend (https://engineering.salesforce.com/investigate-issues-with-ease-by-adding-a-correlation-id-to-your-api-7a689413ff44/).
• Not exposing the ID when helpful. If appropriate for your product and privacy model, return the ID so support and customers can share it when reporting issues (see PayPal’s approach: https://www.paypal.com/us/cshelp/article/what-is-the-%E2%80%9Ccorrelation-id%E2%80%9D-field-in-the-api-used-for-ts1087).

Related reading on Stack & Method

• Idempotency keys: safe retries without duplicate actions
• What are the differences between REST APIs and webhooks?

FAQ

Should clients be allowed to set the correlation ID?

Many systems accept a client-provided ID if it’s present, otherwise they generate one. Some organizations choose to always generate their own at the edge to guarantee uniqueness and consistency; Salesforce describes this approach and returns the ID in responses (https://engineering.salesforce.com/investigate-issues-with-ease-by-adding-a-correlation-id-to-your-api-7a689413ff44/). Microsoft’s guidance emphasizes assigning the ID as early as possible and propagating it through all components (https://microsoft.github.io/code-with-engineering-playbook/observability/correlation-id/).

What format should the ID use?

A randomly generated UUID (such as UUID v4) is a practical default because it’s globally unique and easy to validate in logs (https://last9.io/blog/correlation-id-vs-trace-id/).

Should I include the correlation ID in responses?

It often helps. Microsoft recommends adding it to outgoing responses where possible, and PayPal’s public documentation shows they return a Correlation ID and use it for support lookups (https://microsoft.github.io/code-with-engineering-playbook/observability/correlation-id/, https://www.paypal.com/us/cshelp/article/what-is-the-%E2%80%9Ccorrelation-id%E2%80%9D-field-in-the-api-used-for-ts1087).