---
title: create_distributed_trace_payload (Python agent API)
source: https://docs.newrelic.com/docs/apm/agents/python-agent/python-agent-api/legacy-apis-python-agent-api/createdistributedtracepayload-python-agent-api
---

## Syntax

```py
newrelic.agent.create_distributed_trace_payload()
```

This method is used for generating payloads used to connect transactions within a distributed trace.

## Requirements

Python agent version 4.2.0.100 or higher.

> #### ⚠️ CAUTION
>
> This API was deprecated in version 5.6.0.135 and completely removed in version 11.0.0. Please use [`insert_distributed_trace_headers`](https://docs.newrelic.com/docs/apm/agents/python-agent/python-agent-api/insertdistributedtraceheaders-python-agent-api) instead.

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_payload`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/legacy-apis-python-agent-api/acceptdistributedtracepayload-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 generates a payload that is read by the receiving application with the `accept_distributed_trace_payload` method.

## Return values

When successful, returns a `DistributedTracePayload` object, which inherits from Python's built in `dict` type and has the following additional methods:

-   `text`: Generate a JSON encoded string version of the payload.
-   `http_safe`: Generate a base64 encoded string version of the payload.

When unsuccessful, returns `None`. This can happen when distributed tracing is not enabled or when called from outside an active transaction.

## 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 `create_distributed_trace_payload` in creating two [external traces](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):
    header_key = newrelic.agent.ExternalTrace.cat_distributed_trace_key

    with newrelic.agent.ExternalTrace('my_external_library', url, method='GET'):
        # Generate the payload in the context of the ExternalTrace
        # span that sends it
        payload = newrelic.agent.create_distributed_trace_payload()
        headers = {header_key: payload.http_safe()}
        response = my_external_library._get(url, headers=headers)

    data = _process_response(response)
    
    with newrelic.agent.ExternalTrace('my_external_library', url, method='POST'):
        # Generate the payload in the context of the ExternalTrace
        # span that sends it
        payload = newrelic.agent.create_distributed_trace_payload()
        headers = {header_key: payload.http_safe()}
        response = my_external_library._post(url, data=data, headers=headers)
```

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

An example of using `create_distributed_trace_payload` 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):
    payload = newrelic.agent.create_distributed_trace_payload()
    header_key = newrelic.agent.ExternalTrace.cat_distributed_trace_key
    headers = {header_key: payload.http_safe()}
    return my_external_library._get(url, headers=headers)
```