Authorized Workspace Discovery and Cross-Workspace Query¶

OWL queries the current workspace by default. When you need to query other workspaces, first distinguish between authorized data queries and same-organization trace queries, and then choose the corresponding tool.

Selecting a Query Method¶

Existing discovery results can be reused directly. The same-organization workspace list does not represent general data query authorization and cannot replace the authorized workspace list. If a query fails or returns empty results, do not switch credentials, expand the workspace scope, or switch to another query path.

Upgrade and Member Tool Migration¶

Before use, confirm that the target site supports authorized workspace discovery and cross-workspace queries. After upgrading the CLI to v1.4.0 and upgrading the Registry and tool catalog on the server side, run a full sync; MCP clients rediscover the tools.

owl sync
owl tool list --category workspace

The new workspace category contains owl.workspace.data_authorized.list and owl.workspace.member.list. The old member category is removed. The old name owl.member.list is kept as a call alias for the member tool, reusing the same parameters and permission checks, but it will not appear as a standalone tool in the list.

owl exec owl.workspace.member.list -p '{"search":"alice"}'
# Compatible with old scripts
owl exec owl.member.list -p '{"search":"alice"}'

Older CLI versions do not support aliases; syncing the catalog alone does not guarantee that old commands remain usable. Upgrade the CLI first, then run owl sync. Do not sync only the workspace category.

Discovering Authorized Workspaces¶

owl.workspace.data_authorized.list lists, by site, the workspaces that grant data query permissions to the current workspace.

owl exec owl.workspace.data_authorized.list -p '{}'

Omit optional string parameters when they have no value; do not pass null, an empty string, or whitespace-only values. Use the returned workspace_uuid and region_code to select the target. Do not switch to the target workspace's API Key.

In the returned result, current_workspace is the current workspace, and sites[] contains the workspaces and independent page_info for each site. There is no global page number. When a site still has a next page, keep the filter conditions and query that site separately:

owl exec owl.workspace.data_authorized.list -p '{"region_code":"cn2","page_index":2,"page_size":100}'

Workspaces are identified by (region_code, workspace_uuid). The list indicates that query authorization exists between workspaces. Specific data types and log index permissions are still validated by the query interface. page_size is not an upper limit on the number of workspaces that can be queried.

Querying Data from a Target Site¶

The CLI uses owl.data.query or owl.data.simple_query_file; MCP uses owl.data.simple_query. Cross-workspace queries add the following parameters on top of the existing DQL parameters:

When both are omitted, the current workspace is queried. If only workspace UUIDs are passed, the server derives the site from existing authorization. A single request can select multiple authorized workspaces within one site, but cannot mix multiple sites. When explicitly querying a remote site, you cannot include the current workspace.

workspace_uuids=["*"] means all authorized workspaces in the target site. When the target site is omitted, the current site is used and includes the current workspace. * cannot be mixed with explicit UUIDs, and authorization is re-resolved on each page fetch. Pass explicit UUIDs when you need a fixed query scope.

CLI Example¶

Replace the workspace, site, data source, and time values in the example with actual values. Time uses 13-digit millisecond timestamps. The end time must be later than the start time, and the span is at most 7 days.

owl exec owl.data.simple_query_file -p '{"namespace":"L","source":"nginx","start_time":1772516130000,"end_time":1772516140000,"limit":100,"workspace_uuids":["wksp_b","wksp_c"],"target_region":"cn2"}'

The CLI saves the query results as a data file and retains the workspace and site scope in the file index parameters. Do not assume that every data entry includes a workspace field, and do not attribute all data to the first workspace.

MCP Example¶

In facade mode, first discover the authorized workspace tools in the workspace category, obtain the query scope, and then call through exec_tool:

{
  "tool_name": "owl.data.simple_query",
  "parameters": {
    "namespace": "L",
    "source": "nginx",
    "start_time": 1772516130000,
    "end_time": 1772516140000,
    "workspace_uuids": ["wksp_b", "wksp_c"],
    "target_region": "cn2"
  }
}

In static mode, after discovering tools from tools/list, call tools/call directly with the business tool name, passing the parameters object above as arguments. Both modes use the authentication information of the current connection.

Pagination and Error Handling¶

The authorized workspace list uses page numbers, while data queries use cursors. When data.page_info.has_more=true in a data response, pass the returned next_cursor_time / next_cursor_token directly as the next cursor_time / cursor_token, preserving the original time, conditions, workspace, and site scope.

Cursor time may be in microseconds; do not convert it to 13-digit milliseconds. Do not use the list's page_index or page_size for data queries. Each call retrieves one page only. Subsequent pages must be explicitly requested by the caller.

• First check the CLI's success or MCP's isError before parsing the tool result. For the text tool, the AIAPI response is in the output string of the OWL execution result.
• A successful result with empty data is a valid result. Do not automatically expand the scope and re-query.
• If parameters, authorization, or site are inconsistent, correct the parameters or reconfirm the authorization scope. Do not retry per workspace to bypass the failure.
• If a trace ID or structured error diagnostic fields are returned, keep this information for troubleshooting.
• If the target site does not support the tool or cross-workspace parameters, contact the administrator to confirm the server version first. Do not delete the workspace parameters and retry.