Using Cross-Workspace Trace Queries Within the Same Organization¶

This document describes the configuration toggle, API usage, and common issues for cross-workspace Trace queries within the same organization in Studio on the Deployment Plan.

This capability lets you query trace data across multiple workspaces by a specified trace_id within the same organization. It applies only to Trace query scenarios and does not change the cross-workspace semantics of the regular DQL query APIs.

Prerequisites¶

• The Studio backend version must include the SameOrgTraceQuerySet configuration and the dedicated same-organization Trace query API.
• The target workspaces must belong to the same organization as the current workspace.
• To query workspaces other than the current one, you must enable SameOrgTraceQuerySet.enable.
• No separate parameter adjustment is required on the Kodo side. The Studio backend includes the list of target workspaces in its internal requests.

Configuration Toggle¶

SameOrgTraceQuerySet is located in the Studio backend service configuration and is disabled by default.

SameOrgTraceQuerySet:
  enable: false
  maxWorkspaceCount: 20
  maxLimit: 1000
  maxTimeRangeHours: 24
  workspaceListPageSizeMax: 100

Configuration options:

After enabling the configuration, restart the related Studio backend services.

Toggle Behavior¶

Toggle Disabled¶

When SameOrgTraceQuerySet.enable=false:

• The API for retrieving the simplified workspace info list of the same organization still works normally.
• The Trace query API only allows querying the current workspace.
• If the target workspace UUID list in the request contains a workspace other than the current one, OpenAPI returns code=406 and errorCode=ft.ParameterCheckFailed. This error code is also used for other parameter validation failures, so you cannot determine the toggle status from the error code alone.

If you pass only the current workspace UUID, or omit the workspace UUID list, the behavior is equivalent to querying the trace data of the current workspace.

Toggle Enabled¶

When SameOrgTraceQuerySet.enable=true, the Trace query API accepts multiple workspace UUIDs within the same organization. The server validates the number of workspaces, the time window, and query parameters, and includes the list of target workspaces in the internal query.

Related APIs¶

Retrieve the Simplified Workspace Info List of the Same Organization¶

This API is not controlled by SameOrgTraceQuerySet.enable and can be used to select target workspaces for a Trace query.

OpenAPI:

POST /api/v1/workspace/same_org/list

AIAPI:

POST /api/v1/account/workspace/same_org/list

Common request parameters:

The list is returned in descending order of workspace ID; pageIndex / page_index is not used. The pagination field mapping is as follows:

For example, the first OpenAPI request body is:

{"pageSize": 20}

If the response has hasMore=true and nextBeforeWorkspaceId=12345, the next request is:

{"pageSize": 20, "beforeWorkspaceId": 12345}

The corresponding AIAPI request is:

{"page_size": 20, "before_workspace_id": 12345}

Keep the original workspace filter conditions unchanged during pagination, and stop when hasMore / has_more is false. Workspace IDs are used only for paginating the list; use workspace UUIDs for subsequent Trace queries.

Same-Organization Trace Query¶

OpenAPI:

POST /api/v1/df/same_org/trace/query

AIAPI:

POST /api/v1/data/same_org/trace/query

OpenAPI parameters use lower camelCase, while AIAPI parameters use underscore format.

OpenAPI does not support selectClause or offset. Use cursorTime / cursorToken for pagination; see below for the detailed procedure.

OpenAPI Request Example¶

Replace the workspace IDs, trace ID, and time range in the example with actual values, and keep these query conditions unchanged during pagination.

curl --location 'https://<studio-backend-host>/api/v1/df/same_org/trace/query' \
  --header 'Content-Type: application/json' \
  --header 'DF-API-KEY: <your-openapi-key>' \
  --data '{
    "traceId": "TRACE-XXXX",
    "workspaceUUIDs": ["wksp_xxx", "wksp_yyy"],
    "startTime": 1772516130000,
    "endTime": 1772519730000,
    "limit": 100
  }'

AIAPI Request Example¶

{
  "trace_id": "TRACE-XXXX",
  "workspace_uuids": ["wksp_xxx", "wksp_yyy"],
  "where_clause": "`service` = 'api'",
  "start_time": 1772516130000,
  "limit": 100
}

Trace Scroll Pagination¶

For OpenAPI, the result of a single query is in content.data[0]; for AIAPI, the corresponding location is data.data[0]. Read next_cursor_time and next_cursor_token from it.

1. On the first query, you can omit the cursor or set cursorTime / cursor_time to the 13-digit millisecond timestamp of the query end time.
2. Stop pagination when next_cursor_time < 0; do not pass this negative value back to the API.
3. To request the next page, pass next_cursor_time back as-is along with the non-empty next_cursor_token. Subsequent cursors may be 16-digit microsecond timestamps; do not convert them to milliseconds, otherwise you may miss data near the same timestamp.
4. When next_cursor_token is empty, you can omit it or pass an empty string. When there is no valid next_cursor_time, do not construct a cursor manually or keep repeating the request; record the response and investigate.

Assuming the previous page returned next_cursor_time as 1772519729000123 and next_cursor_token as cursor_example, the OpenAPI next-page request body is:

{
  "traceId": "TRACE-XXXX",
  "workspaceUUIDs": ["wksp_xxx", "wksp_yyy"],
  "startTime": 1772516130000,
  "endTime": 1772519730000,
  "limit": 100,
  "cursorTime": 1772519729000123,
  "cursorToken": "cursor_example"
}

The cursors above are examples only; actual requests must use the values from the previous page's response. AIAPI uses cursor_time / cursor_token, and the remaining fields use the underscore naming described earlier. startTime / endTime (or start_time / end_time) must remain the original millisecond time range and cannot be converted along with the pagination cursor. If you used source or filter conditions, keep them unchanged when paging.

FAQ¶

ft.ParameterCheckFailed returned¶

When the cross-workspace Trace query toggle is disabled and you request another workspace, OpenAPI returns this error. The same error may also be returned when the target workspace does not belong to the same organization or when the time range or other parameters are invalid, so check the request parameters.

To resolve:

• First verify the time range, cursor, workspace ownership, and site configuration.
• If you only need to query the current workspace, remove the other workspace UUIDs.
• If you really need cross-workspace queries, enable SameOrgTraceQuerySet.enable in the Studio backend configuration and restart the service.

Can the original query_data APIs still accept a same-organization workspace list?¶

No. /api/v1/df/query_data, /api/v1/df/query_data_v1, /api/v1/df/asynchronous/query_data, and the regular DQL query APIs on AIAPI no longer accept entry parameters for cross-workspace queries within the same organization. Use the dedicated same-organization Trace query API instead.

How to query when no end time is passed¶

If endTime / end_time is not passed, the DQL time_range composed internally by the server contains only the start time. If the start time is also not passed, the server uses the start of the last 1 hour by default.