# List agents referencing a knowledge base

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

List agents whose effective bindings reference the knowledge base, within the current identity's visibility.

```text
GET https://api.moi.matrixorigin.cn/v5/semantic-models/{model_id}/referencing-agents
```

## Before you call this API

Prepare current Workspace credentials and resource privileges. See [Shared information](objects.md) for variables, import files, and operation boundaries.

## Query parameters

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Request example

```bash
curl -X GET "https://api.moi.matrixorigin.cn/v5/semantic-models/$MODEL_ID/referencing-agents" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  --get \
  --data-urlencode "limit=50" \
  --data-urlencode "cursor=${NEXT_CURSOR:-}"
```

:::::
:::::{tab-item} Parameters

The service combines current Workspace and system agent definitions with Workspace binding overrides, then filters by identity. Archived agents are excluded. Use the actual response limit; an early return without visible permission candidates may use 0. Advance by next_cursor, not by empty items or items shorter than limit: archival filtering follows pagination and may produce empty intermediate pages. No total is returned. Results do not establish globally absent references or safe deletion.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `model_id` | integer | Required in path | Positive integer knowledge base ID in the current Workspace; model read privileges and existence are checked first. |
| `limit` | integer | No | Defaults to 50. Explicit values must be positive integers; values above 200 become 200. |
| `cursor` | string | No | Previous next_cursor; omit or leave empty for the first page. Cannot be reused across Workspaces or resources. |

:::::
::::::
:::::::

## Successful response

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "items": [],
    "limit": 50
  }
}
```

:::::
:::::{tab-item} Fields

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | OK on success. |
| `msg` | string | Response information. |
| `data` | object | Current operation result. Single-object imports return a knowledge base object directly. |
| `data.items` | object[] | Visible, nonarchived referencing agents on this page. |
| `data.items[].id` | string | Agent ID. |
| `data.items[].workspace_id` | string | Workspace owning the agent definition; may differ from the query Workspace. |
| `data.items[].name` | string | Name. |
| `data.items[].description` | string | Description. |
| `data.items[].status` | string | Agent status. |
| `data.items[].updated_at` | string | RFC 3339 timestamp. |
| `data.items[].knowledge_base_count` | integer | Knowledge base references in this agent's effective bindings, not the global reference total for this query. |
| `data.limit` | integer | Effective page size. |
| `data.next_cursor` | string | Continue with the same resource when present and nonempty; may be omitted at the end. |

:::::
::::::
:::::::

## Error responses

Check HTTP, business code, and target resource separately. Retain request information and read back as described in [Errors and environments](objects.md#错误与环境).
