# List connectors

List connectors that you can read in the current workspace. Use this endpoint to find a connector ID, then get its details, update or delete it, or create a data task.

```text
GET https://moi.matrixorigin.cn/newmoi/connectors/list
```

## Before you call

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

The example uses:

- `$AI_STUDIO_API_KEY`: your personal access token, sent in the `X-API-Key` header.
- `$WORKSPACE_ID`: the workspace to query, sent in the `X-Workspace-ID` header.

## Request example

```bash
curl "https://moi.matrixorigin.cn/newmoi/connectors/list?page=1&page_size=20" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

To filter by name, append `name` as a query parameter.

## Query parameters

Without query parameters, the endpoint returns the first page of connectors. Use filters to narrow the result set, and use `page` and `page_size` to paginate it.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | No | Filter by name. |
| `page` | integer | No | Page number. The default is `1`. |
| `page_size` | integer | No | Number of items per page. The default is `20`. |
| `order_by` | string | No | Sort field. Results are sorted by creation time in descending order when omitted. |
| `is_desc` | boolean | No | Whether to sort in descending order when `order_by` is set. |
| `keyword` | string | No | Keyword filter. |
| `source_type` | integer | No | Filter by one data-source type. |
| `source_type_list` | integer[] | No | Filter by multiple data-source types. This parameter can be repeated. |
| `status` | string | No | Filter by one connector status. |
| `status_list` | string[] | No | Filter by multiple connector statuses. This parameter can be repeated. |
| `usage_type` | integer[] | No | Filter by connector purpose. |

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

## Successful response

A successful request returns `200`. Get connector information from `data.connectors[]`, and use `data.total` to determine the number of matching results.

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "connectors": [
      {
        "id": "conn_01",
        "name": "s3-orders-import",
        "source_type": 5,
        "created_at": 1735632000,
        "updated_at": 1735718400,
        "status": "active",
        "username": "reader",
        "related_task_ids": ["task_01"],
        "usage_type": [1],
        "config": {
          "s3": {
            "endpoint": "https://s3.example.com",
            "bucket_name": "orders",
            "region": "us-east-1"
          }
        }
      }
    ],
    "total": 1
  }
}
```

Response fields are as follows.

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | `OK` on success. |
| `msg` | string | `OK` on success. |
| `data.connectors` | object[] | Connectors matching the current filters. |
| `data.connectors[].id` | string | Connector ID. |
| `data.connectors[].name` | string | Connector name. |
| `data.connectors[].source_type` | integer | Data-source type code. |
| `data.connectors[].created_at` | integer | Creation time as a Unix timestamp. |
| `data.connectors[].updated_at` | integer | Update time as a Unix timestamp. |
| `data.connectors[].status` | string | Current connector status. |
| `data.connectors[].username` | string | User name in the configuration. |
| `data.connectors[].related_task_ids` | string[] | IDs of related data tasks. |
| `data.connectors[].usage_type` | integer[] | Saved purpose list expanded by the service from the bitmask. For example, `[1]` is import only, `[2]` is export only, and `[1, 2]` supports both. |
| `data.connectors[].config` | object | Type-specific connection configuration. For top-level keys and complete fields, see [Type-specific configuration fields for creating a connector](create-connector.md#type-specific-configuration-fields). Response fields depend on the actual data-source type. |
| `data.total` | integer | Total number of connectors matching the filters. |

In this document, `[]` after a type means an array. In field paths, `[]` means each item in an array.

## Read the next page

Use `data.total` and the requested `page_size` to calculate the last page, then increase `page` in sequence. For example, when `total` is `41` and `page_size` is `20`, request pages `1`, `2`, and `3`.

## Error response

```json
{
  "code": "ErrForbidden",
  "msg": "permission denied",
  "data": null
}
```

### Common HTTP errors

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

* - HTTP status
  - Error code
  - Common cause
  - Recommended action
* - `400`
  - `ErrParamInvalid`
  - A query parameter has an invalid format.
  - Correct the parameter and retry.
* - `403`
  - `ErrForbidden`
  - The caller cannot read the connector collection.
  - Check workspace and connector permissions.
* - `503`
  - `ErrCoreAuthorizeUnavailable`
  - The service cannot complete authorization filtering.
  - Retry later; do not treat an empty list as meaning that no connectors exist.
```

## Next steps

Keep the target connector's `id`, then [get connector details](get-connector.md). To select databases or tables, [view browsable connectors](../connector-data-sources/list-structured-data-sources.md); to browse files, [list files](../connector-files/list-files.md).