---
orphan: true
---

# Query the list of agent task templates

Query the agent task templates in the workspace and filter by associated agent, status or name.

```text
GET https://moi.matrixorigin.cn/newmoi/workspaces/{workspace_id}/agent-task-templates
```

## Before you call

Prepare a personal access token and workspace ID that has access to the target workspace.

The example below uses:

- `$AI_STUDIO_API_KEY`: The actual personal access token, passed through the `X-API-Key` Header.
- `$WORKSPACE_ID`: Target workspace ID, also as `workspace_id` in the path.

## Request example

```bash
curl "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/agent-task-templates?limit=20&offset=0" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

## Path parameters

| Parameters | Type | Is it required | Description |
| --- | --- | --- | --- |
| `workspace_id` | string | Yes | The target workspace ID. |

## Query parameters

| Parameters | Type | Is it required | Description |
| --- | --- | --- | --- |
| `agent_id` | string | No | The associated agent ID. |
| `status` | string | No | Template status. |
| `query` | string | No | Filter by template name or description. |
| `limit` | integer | No | Return the quantity. |
| `offset` | integer | No | Return to the starting position. |

## Successful response

Returns `200` and the template summary of the current page on success.

```json
{
  "code": 0,
  "data": {
    "items": [{"id": "template_01", "agent_id": "agent_01", "name": "摘要任务"}],
    "total": 1,
    "limit": 20,
    "offset": 0
  }
}
```

The response fields are as follows.

| Field | Type | Description |
| --- | --- | --- |
| `code` | integer | `0` on success. |
| `data.items` | array | The task template of the current page. |
| `data.items[].id` | string | Template ID. |
| `data.items[].agent_id` | string | Associated agent ID. |
| `data.items[].name` | string | Template name. |
| `data.total` | integer | The total number of matches. |
| `data.limit` | integer | Current page size. |
| `data.offset` | integer | Current page offset. |

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


## Error response

```json
{"code": 2, "message": "invalid agent task template filter"}
```

### Common HTTP errors

```{list-table}
:header-rows: 1

* - HTTP status code
  - error code
  - Common causes
  - Recommended actions
* - `400`
  - `2`
  - Invalid filter or paging parameters.
  - Check query parameters.
* - `401`
  - `6`
  - Lack of valid identity credentials.
  - Check API Key.
```

## Follow-up operations

Record `data.items[].id`, and then [Query the details of the agent task template](get-task-template.md).