---
title: insert_distributed_trace_headers (Python agent API)
source: https://docs.newrelic.com/docs/apm/agents/python-agent/python-agent-api/insertdistributedtraceheaders-python-agent-api
---

## Syntax

```py
newrelic.agent.insert_distributed_trace_headers(list_of_headers)
```

This method is used for inserting headers used to connect transactions within a distributed trace.

## Requirements

Python agent version 5.6.0.135 or higher.

Distributed tracing must be [enabled](https://docs.newrelic.com/docs/enable-distributed-tracing#python).

## Description

This API requires [distributed tracing to be enabled](https://docs.newrelic.com/docs/enable-distributed-tracing).

For instructions on how to use this call, along with its partner call [`accept_distributed_trace_headers`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/acceptdistributedtraceheaders-python-agent-api), see [Enable distributed tracing with agent APIs](https://docs.newrelic.com/docs/enable-distributed-tracing#agent-apis).

This call is used to implement distributed tracing. It inserts headers into a list that can be read by the receiving application with the `accept_distributed_trace_headers` method.

## Parameters

| Parameter        | Description                                                                                                                                               |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `headers` _list_ | Required. A list of headers. This list will be mutated by the call (headers will be inserted into the list in the form of `(header_name, header_value)`). |

## Return values

Returns `None`. The input list will be updated by a call to this function.

## Examples

> #### ⚠️ IMPORTANT
>
> In order to maintain proper ordering of spans in a trace, you must generate the payload in the context of the span that sends it.

### Create a distributed trace payload inside a background task [#function-trace-example]

An example of using `insert_distributed_trace_headers` in creating an [external trace](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/external-trace) from within single a background task:

```py
@newrelic.agent.background_task()
def main(url):
    with newrelic.agent.ExternalTrace('my_external_library', url, method='GET'):
        # Generate the payload in the context of the ExternalTrace
        # span that sends it
        headers = []
        newrelic.agent.insert_distributed_trace_headers(headers)
        response = my_external_library._get(url, headers=headers)

    data = _process_response(response)
```

### Create a distributed trace payload inside an external trace [#function-trace-example]

An example of using `insert_distributed_trace_headers` in creating an [external trace](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/external-trace):

```py
def _bind_url(url, *args, **kwargs):
    # _bind_url is called with the args and kwargs sent to the `get`
    # method below
    return url

@newrelic.agent.external_trace('my_external_library', _bind_url, method='GET')
def get(url):
    headers = []
    newrelic.agent.insert_distributed_trace_headers(headers)
    return my_external_library._get(url, headers=headers)
```