Authorized Workspace Discovery and Cross-workspace Queries¶

OWL queries the current workspace by default. When querying other workspaces, distinguish authorized data queries from same-organization Trace queries and choose the corresponding tools.

Choose the Query Scope¶

Reuse known discovery results. A same-organization workspace list does not establish authorization for ordinary data queries. Do not switch credentials, broaden the scope, or fall back to another query path after an error or an empty result.

Upgrade and Member Tool Migration¶

Confirm that the target site supports authorized workspace discovery and cross-workspace queries. Upgrade the CLI to v1.4.0 and update the Registry and tool catalog together. Then run a full synchronization; MCP clients must rediscover 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. owl.member.list remains a callable alias with the same parameters and permission checks, but is not listed as a separate tool.

owl exec owl.workspace.member.list -p '{"search":"alice"}'
owl exec owl.member.list -p '{"search":"alice"}'

Older CLI versions do not support aliases. Synchronizing the catalog alone does not make old commands compatible: upgrade the CLI first, then run owl sync rather than synchronizing only the workspace category.

Discover Authorized Workspaces¶

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

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

Omit optional strings when unused; do not pass null, empty strings, or whitespace-only strings. Select targets using the returned workspace_uuid and region_code, without switching API Keys.

current_workspace identifies the current workspace. Each entry in sites[] has its own workspaces and page_info; there is no global page number. To continue a site with more results, keep the filters and request that site separately:

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

Identify each workspace by (region_code, workspace_uuid). The list establishes workspace query grants; the query endpoint still checks data type and log index permissions. page_size is not a limit on the number of workspaces in a query.

Query Data at One Target Site¶

Use owl.data.query or owl.data.simple_query_file in the CLI, and owl.data.simple_query in MCP. Cross-workspace DQL queries add these parameters:

Omitting both parameters queries the current workspace. If only UUIDs are supplied, the server infers the site from existing grants. A request may select multiple authorized workspaces at one site, but cannot mix sites. An explicit remote-site query cannot include the current workspace.

workspace_uuids=["*"] selects all authorized workspaces at the target site. Without a target site, it uses the current site and includes the current workspace. Do not mix * with explicit UUIDs. Grants are resolved again for every page; use explicit UUIDs when the selected scope must stay fixed.

CLI Example¶

Replace the example workspaces, site, source, and time range with actual values. Use 13-digit millisecond timestamps; the end must be later than the start, and the range must not exceed 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 results as a data file and retains the workspace and site scope in the file index parameters. Do not assume every row includes a workspace field or attribute all rows to the first workspace.

MCP Example¶

In facade mode, discover the authorized workspace tool in the workspace category, select the query scope, and call 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, discover tools with tools/list, call tools/call with the business tool name, and use the parameters object above as arguments. Both modes retain the current connection credentials.

Pagination and Error Handling¶

Workspace discovery uses page numbers; data queries use cursors. When data.page_info.has_more=true, pass the returned next_cursor_time / next_cursor_token unchanged as the next cursor_time / cursor_token, retaining the original time range, filters, workspaces, and site.

Cursor times may use microseconds; do not convert them to 13-digit milliseconds. Do not use the list parameters page_index and page_size for data queries. Each call retrieves one page; callers request subsequent pages explicitly.

• Check CLI success or MCP isError before parsing results. For text tools, the AIAPI response is in the OWL result's output string.
• A successful empty result is valid; do not automatically broaden the query scope.
• For parameter, authorization, or site errors, correct the request or confirm grants. Do not retry workspace by workspace to bypass a failure.
• Keep any returned trace ID or structured diagnostic fields for troubleshooting.
• If the site does not support the tool or cross-workspace parameters, confirm the server version with an administrator. Do not remove workspace parameters and retry.