---
title: Topology Map Widget
description: >-
  Displays a map of a service to all of the services that call it, and all of
  the services that it calls.
breadcrumbs: Docs > Dashboards > Widgets > Topology Map Widget
---

> For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt).

# Topology Map Widget

The Topology Map widget displays a visualization of data sources and their relationships to help understand how data flows through your architecture.

## Setup{% #setup %}

### Configuration{% #configuration %}

1. Choose the data source to graph:

| Data source                                                                   | What the node represents                                                        | What the lines represent                                                |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| [Service Map](https://docs.datadoghq.com/tracing/services/services_map.md)    | The mapped service, which is the service selected in the widget's configuration | An upstream-to-downstream relationship, in either direction             |
| [Data Streams](https://docs.datadoghq.com/data_streams.md)                    | A component in a data pipeline, such as a service or queue                      | The flow of data between producers and consumers in the pipeline        |
| [Network Path](https://docs.datadoghq.com/network_monitoring/network_path.md) | A hop along a network path                                                      | The latency-annotated link between two hops, from source to destination |

For Service Map, if another service calls the mapped service, a line points from that service to the mapped service. If the mapped service calls other services, a line points from the mapped service to each of those services.

1. Enter a title for your graph.

## API{% #api %}

This widget can be used with the **[Dashboards API](https://docs.datadoghq.com/api/latest/dashboards.md)**. See the following table for the [widget JSON schema definition](https://docs.datadoghq.com/dashboards/graphing_json/widget_json.md):

{% tab %}
ModelExample
{% tab title="-model" %}
Expand AllFieldTypeDescription custom_links[object]List of custom links.is_hiddenbooleanThe flag for toggling context menu link visibility.labelstringThe label for the custom link URL. Keep the label short and descriptive. Use metrics and tags as variables.linkstringThe URL of the custom link. URL must include `http` or `https`. A relative URL must start with `/`.override_labelstringThe label ID that refers to a context menu link. Can be `logs`, `hosts`, `traces`, `profiles`, `processes`, `containers`, or `rum`.descriptionstringThe description of the widget. requests [*required*][object]One Topology request. queryobjectQuery to the service map topology data source.data_source [*required*]enumName of the data source. Allowed enum values: `service_map`filters [*required*][string]Your environment and primary tag (or * if enabled for your account).query_stringstringA search string for filtering services. When set, this replaces the `service` field.service [*required*]string(deprecated) Name of the service. Leave this empty and use query_string instead.request_typeenumWidget request type. Allowed enum values: `topology` time <oneOf>Time setting for the widget. Object 1objectWrapper for live spanhide_incomplete_cost_databooleanWhether to hide incomplete cost data in the widget.live_spanenumThe available timeframes depend on the widget you are using. Allowed enum values: `1m,5m,10m,15m,30m,1h,4h,1d,2d,1w`Show 7 more`,1mo,3mo,6mo,week_to_date,month_to_date,1y,alert`

 <type=live>objectUsed for arbitrary live span times, such as 17 minutes or 6 hours.hide_incomplete_cost_databooleanWhether to hide incomplete cost data in the widget.type [*required*]enumType "live" denotes a live span in the new format. Allowed enum values: `live`unit [*required*]enumUnit of the time span. Allowed enum values: `minute,hour,day,week,month,year`value [*required*]int64Value of the time span. <type=fixed>objectUsed for fixed span times, such as 'March 1 to March 7'.from [*required*]int64Start time in milliseconds since epoch.hide_incomplete_cost_databooleanWhether to hide incomplete cost data in the widget.to [*required*]int64End time in milliseconds since epoch.type [*required*]enumType "fixed" denotes a fixed span. Allowed enum values: `fixed`titlestringTitle of your widget.title_alignenumHow to align the text on the widget. Allowed enum values: `center,left,right`title_sizestringSize of the title.type [*required*]enumType of the topology map widget. Allowed enum values: `topology_map`
default: `topology_map`
{% /tab %}

{% tab title="example" %}

```json
{
  "custom_links": [
    {
      "is_hidden": false,
      "label": "Search logs for {{host}}",
      "link": "https://app.datadoghq.com/logs?query={{host}}",
      "override_label": "logs"
    }
  ],
  "description": "string",
  "requests": [
    {
      "query": {
        "data_source": "service_map",
        "filters": [
          "env:prod",
          "az:us-east"
        ],
        "query_string": "service:myservice",
        "service": "myservice"
      },
      "request_type": "string"
    }
  ],
  "time": {
    "hide_incomplete_cost_data": false,
    "live_span": "5m"
  },
  "title": "string",
  "title_align": "string",
  "title_size": "string",
  "type": "topology_map"
}
```

{% /tab %}

{% /tab %}

## Further Reading{% #further-reading %}

- [Building Dashboards using JSON](https://docs.datadoghq.com/dashboards/graphing_json.md)
- [Service Map](https://docs.datadoghq.com/tracing/services/services_map.md)