> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluz.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 发现已连接的用户

> 返回通过有效 OAuth 授权连接到您应用的用户，以及他们的外部参考 ID 和授予的作用域。

返回通过有效 OAuth 授权连接到您应用的用户，并包含每个用户的 `externalReferenceId` 和其授予的作用域。在调用其他批量操作之前，使用它来查看您可以触达的对象以及每位用户已授权的内容。

仅返回标识符和授予的作用域——**绝不包含用户令牌**。

## 要求

* `Authorization: Basic <API_KEY>`（您的应用 API key）
* 您的应用已启用**批量 API 能力**

## 查询

```graphql theme={null}
query GetBulkConnectedOAuthUsers($paginate: BulkPaginationInput) {
  getBulkConnectedOAuthUsers(paginate: $paginate) {
    totalCount
    hasNextPage
    users {
      externalReferenceId
      accountId
      userId
      scopes
      connectedAt
    }
  }
}
```

### 变量

```json theme={null}
{
  "paginate": { "limit": 100, "offset": 0 }
}
```

## 响应

```json theme={null}
{
  "data": {
    "getBulkConnectedOAuthUsers": {
      "totalCount": 128,
      "hasNextPage": true,
      "users": [
        {
          "externalReferenceId": "your-user-001",
          "accountId": "8f3c…",
          "userId": "b21a…",
          "scopes": ["LIST_PAYMENT", "LIST_PURCHASES"],
          "connectedAt": "2026-05-01T12:00:00.000Z"
        }
      ]
    }
  }
}
```

## 参数

| 参数                | 类型    | 描述                      |
| ----------------- | ----- | ----------------------- |
| `paginate.limit`  | `Int` | 每页用户数。最大值和默认值为 **100**。 |
| `paginate.offset` | `Int` | 需要跳过的用户数量。默认值为 `0`。     |

## 响应字段

| 字段                            | 描述                                                             |
| ----------------------------- | -------------------------------------------------------------- |
| `users[].externalReferenceId` | 您为该用户设置的参考 ID。若连接时未设置则为 `null`——此类用户只能通过 `ALL_CONNECTED` 进行触达。 |
| `users[].accountId`           | 已连接用户的账户 ID。                                                   |
| `users[].userId`              | 已连接用户的用户 ID。                                                   |
| `users[].scopes`              | 用户授予您应用的作用域。                                                   |
| `users[].connectedAt`         | 用户连接的时间。                                                       |
| `totalCount`                  | 所有页面上的已连接用户总数。                                                 |
| `hasNextPage`                 | 是否在本页之后还有更多用户。                                                 |

## 备注

* 批量 API 允许的每页大小比其他 API 更大——最多 100 条/页。
* 使用 `offset` 分页，直到 `hasNextPage` 为 `false`。