Export Service Map via External API¶

This document explains how to use the TrueWatch External API to retrieve service nodes and call relationships, and to aggregate Service Map data within a specified site by querying workspace by workspace.

The API returns JSON. Generating CSV, Excel, or an application dependency manifest requires the caller to organize the returned results.

Applicable Scope¶

• Query the APM Service Map collected within a specified time range to sort out call relationships between services.
• For a single workspace, use the Service Map API; for all workspaces in a site, use the "paginate the workspace list → query the topology of each workspace → aggregate the results" flow.
• Export results are affected by collection completeness, data retention time, and deployment version. They do not represent all historical dependencies or call relationships that were not collected.
• This document specifies one workspaceUUID per request. The console's cross-workspace selector works differently from this flow; do not combine multiple UUIDs or * into workspaceUUID.

If you need to analyze call relationships between different workspaces, confirm that the corresponding collection and cross-workspace topology capabilities are already in place at the site. See Cross-Workspace Configuration for APM Service Map. Aggregating workspace by workspace will not add cross-workspace call edges that do not exist in the source data.

Prerequisites¶

1. Confirm the External API Endpoint of the current site. It is usually https://external-api.truewatch.com. Follow the actual deployment address; do not use the console front or the OpenAPI Endpoint as a substitute.
2. Prepare the AK/SK for the External API and generate the request headers according to API Signature Authentication. Do not replace the signature with the workspace OpenAPI DF-API-KEY.
3. On versions that support External read-only accounts, a read-only account can be used to call the two query APIs in this document. Accounts are configured by the site administrator.
4. Fix a pair of start and end values, both of which are millisecond timestamps, and start < end. All workspaces use the same time range. X-Df-Timestamp in the signature header is the second timestamp when each request is made.
5. First select one workspace and verify the response using the same time range and filter conditions as the console, then start the batch export. Support for parameters such as the newly added grouping in the Deployment Plan depends on the version deployed at your site.

Step 1: Paginate the Workspace List¶

Call the List Workspaces API:

GET /api/v1/workspace/list?pageIndex=1&pageSize=100

pageIndex starts at 1; pageSize has a maximum of 100. Do not pass search when exporting all workspaces in the site.

Read the following from the response:

Increment pageIndex by 1 each time until all paginated results are traversed. Deduplicate by UUID and save the list of workspaces actually queried this run. If an empty page is returned before the total count is reached, record the anomaly and re-check; do not simply declare that all workspaces were exported successfully. Paginated results may also change if workspaces are created or deleted during the export.

Step 2: Retrieve the Service Map of Each Workspace¶

Call the Service Map API:

GET /api/v1/tracing/service_map_v2?workspaceUUID=wksp_example&start=1789430400000&end=1789516800000

The example time range is from 2026-09-15 08:00 to 2026-09-16 08:00 Beijing time. Replace it with a range that you actually need and that is still within the data retention period.

The following request shows the signature headers that must be included. It cannot be executed directly with placeholders:

curl '<Endpoint>/api/v1/tracing/service_map_v2?workspaceUUID=wksp_example&start=1789430400000&end=1789516800000' \
  -H 'X-Df-Access-Key: <AK>' \
  -H 'X-Df-SVersion: v20240417' \
  -H 'X-Df-Timestamp: <current second timestamp>' \
  -H 'X-Df-Nonce: <random nonce for this request>' \
  -H 'X-Df-Signature: <signature computed from the final request path>'

A new nonce, timestamp, and signature must be regenerated for each request. The signature uses the original path and query string of the final request sent; after adding parameters such as groupBy or applying URL encoding, re-sign using the final path.

Selecting the Query Scope¶

groupBy affects node identity, so all workspaces should use the same grouping criteria. When a central service is specified and grouping is enabled, fields such as centralWorkspaceUUID and centralEnv can be used to further locate the central node. See the API parameter documentation for details.

The console's single-service "upstream/downstream" view includes a central service restriction and cannot be directly treated as the topology of the entire workspace. When comparing the page with the API, align the time, workspace, grouping, and filter conditions at the same time. Display attributes such as graph layout and node colors are not business relationships that need to be exported.

For export, read content.services and content.maps directly. Do not rely on serviceMapList=true to generate additional lists or download files.

Step 3: Save Nodes, Call Edges, and Execution Results¶

For each request, first check the HTTP status and the code, success, and errorCode fields in the response. On success, save the complete JSON along with the workspace UUID, time range, and grouping parameters of this query.

See Service Map Response Example for a redacted excerpt of a response verified in a test environment. The example keeps the fields and statistical values of the selected nodes and call edges and cannot replace response verification at your site.

It is recommended to output two types of files:

• Raw JSON: Save separately by queried workspace, keeping nodes, edges, statistical values, and the response traceId for later review.
• Call Relationship Table: Each row records one directed call relationship, including at least the queried workspace, source workspace, source service, target workspace, target service, start time, and end time. Add node IDs and grouping dimensions based on the actual response.

Aggregation rules:

1. A → B and B → A are two different relationships.
2. Services with the same name in different workspaces must not be merged by name alone. Prefer "workspace identity + node ID"; when the ID is missing, use "workspace identity + service name + selected grouping dimensions". If the workspace identity cannot be confirmed, mark the entry as pending verification and do not guess the workspace of the other end of an edge based on the queried workspace.
3. The same call edge may appear in query results from multiple workspaces. The relationship table can be deduplicated by the directed edges formed by the node identities above, while keeping the originating query workspace; the raw JSON is not deduplicated.
4. Do not directly add up the request counts of duplicate edges, and do not directly average request rates, error rates, or P99. If global statistics are needed, define a separate aggregation approach.
5. Save services and maps separately. Extracting nodes only from call edges may miss services without call edges.
6. Missing fields must not be treated as 0. In particular, distinguish between "not returned" and "returned as zero" for statistical fields.

Batch Execution Flow¶

The following is pseudocode for the flow. Signing client implementations can reuse the Python example in API Signature Authentication.

Fix start, end, and groupBy
Paginate through workspace/list, save and deduplicate by uuid to get the workspace list
If the workspace list fails to be read: stop and mark this export as incomplete

For each workspace in the list, execute serially:
    Regenerate the signature and query service_map_v2
    If the HTTP or business status fails:
        Record the failed workspace, error code, and traceId, and continue with other workspaces
    If successful but the services/maps structure is abnormal:
        Save the raw response, mark the structure as abnormal, and do not treat it as an empty topology
    If successful and the structure is normal:
        Save the raw JSON
        If both services and maps are empty, record "no topology data for this time range"
        Otherwise, organize the call relationship table by node identity

Output the total number of workspaces, number of successes, number with no data, number of failures, and the list of failed workspaces
If there are failures or structural anomalies: mark the results as partially complete
Retry the failed workspaces within the same time range, then update the aggregated results

It is recommended to run queries serially first and set a reasonable request timeout. When there are many workspaces, control concurrency based on the load at your site. The Service Map API does not expose pagination parameters like pageIndex/pageSize; do not apply the workspace list pagination approach to obtain more call edges. When the data volume is large, check the query limits and response completeness at your site.

Validation and Troubleshooting¶

Before releasing to a customer environment, it is recommended to verify at least: a workspace with call relationships, a workspace without topology data, workspace list pagination, recording of failed workspaces, and differentiation of services with the same name across different workspaces.