Query the agent that references this skill¶

Lists the agents in the current workspace that are effectively bound to the specified skill. The response only contains a summary of the agent display and does not return the full definition of the agent.

HTTP
GET $CLOUDSIGMA_API_BASE/workspaces/{workspace_id}/skills/{skill_id}/referencing-agents

Before you call this API¶

Configure the regional API endpoint and authentication, and select the target workspace.

First query the skill list to obtain the skill ID.

Set the operation-specific values used in the request:

$SKILL_ID: The referenced skill ID.

Request¶

Input examples

Shell
curl "$CLOUDSIGMA_API_BASE/workspaces/$WORKSPACE_ID/skills/$SKILL_ID/referencing-agents?limit=20" \
  -H "X-API-Key: $CLOUDSIGMA_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"

Parameter reference

Path parameters

Parameters	Type	Is it required	Description
`workspace_id`	string	Yes	Query the current workspace ID of the reference relationship.
`skill_id`	string	Yes	The skill ID being referenced.

Query parameters

Parameters	Type	Is it required	Description
`skill_workspace_id`	string	No	The workspace to which the skill belongs; can only be the current workspace or `system`. When not provided, if the skill is not found in the current workspace, it will continue to search for system skills.
`limit`	integer	No	Quantity per page. Default `50`, maximum `200`.
`cursor`	string	No	`next_cursor` returned from the previous page. Cursors must be used with the same workspace and skill set.

Successful response¶

Returns 200 on success. If there is still data later, use next_cursor to query the next page.

Response example

JSON
{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "agent_01",
        "workspace_id": "ws_01",
        "name": "数据助手",
        "status": "active"
      }
    ],
    "limit": 20,
    "next_cursor": "cursor_01"
  }
}

Field reference

The response fields are as follows.

Field	Type	Description
`code`	integer	`0` on success.
`data.items`	array	A summary of the agent display that references this skill.
`data.items[].id`	string	Agent ID and workspace.
`data.items[].workspace_id`	string	Agent ID and workspace.
`data.items[].name`	string	Agent name and status.
`data.items[].status`	string	Agent name and status.
`data.limit`	integer	The actual page size used by this page.
`data.next_cursor`	string	Next page cursor; does not return when there is no more data.

[] after a type denotes an array. [] in a field path denotes each item in an array.

Error response¶

Response example

JSON
{
  "code": 2,
  "message": "<错误信息>"
}

Field reference

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`2`（`INVALID_ARGUMENT`）	The skill ID, `skill_workspace_id`, or cursor is invalid, or the cursor does not fall within the current skill range.	Use the cursor returned as is, and check the path and query parameters.
`401`	`6`（`UNAUTHENTICATED`）	Lack of valid identity credentials.	Check API Key.
`403`	`5`（`PERMISSION_DENIED`）	The current identity does not have permission to read skills or candidate agents.	Check workspace authorization.
`404`	`3`（`NOT_FOUND`）	This skill does not exist in the current or rollback system directories.	Check skill ID and `skill_workspace_id`.
`503`	`15`（`UNAVAILABLE`）	The skill or agent reference service is temporarily unavailable.	Try again later.

Follow-up operations¶

This list is used to evaluate which agents the skill is referenced by. Before adjusting skills, confirm the citation source, and then Query skill details or Update skills.

Last updated on Sep 15, 2026