Composio API 分页机制详解：端点级限制与 next_cursor 游标分页实战指南

Composio API 分页机制详解端点级限制与 next_cursor 游标分页实战指南【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio本文聚焦 Composio 平台 API 的分页行为核心结论是Composio不存在全局统一的页大小上限不同资源端点资源列表、目录、Tool Router、日志、计费等各自定义分页限制其中GET /api/v3/auth_configs与GET /api/v3.1/auth_configs当前每页最多返回 50 条。读完本文你将掌握基于next_cursor的游标分页完整流程、Python / TypeScript SDK 的正确调用方式以及如何规避文档宣传上限与实际端点截断不一致这一常见陷阱确保在 Auth Config 数量增长时不会漏数据。一、Composio 分页的核心原则没有全局页大小只有端点级限制Composio API 的分页设计并不遵循一刀切的全局页大小策略。根据 platform-pagination 知识库文档 的说明资源列表resource lists如 Auth Config、Connected Account 等列表端点各自定义分页上限目录catalogs如 Toolkit、工具目录类端点独立定义返回条数Tool Router会话工具列表端点拥有自己的页大小常量日志logs与计费billing端点同样各自为政Toolkit Actions还会继承第三方 Provider 自身的分页规则即上游 API 限制会传导到 Composio 的返回行为上。因此在任何端点报出一个最大页大小之前都应先核对对应端点的 schemaOpenAPI 定义与线上实际行为而不是凭经验假设一个通用的 limit 值。这一点在排查分页问题时尤其重要同一套代码里不同列表接口的翻页行为可能完全不同。从源码看端点级限制的实现证据Composio TypeScript SDK 在 pagination.ts 中提供了一套通用的游标翻页工具getAllPages其内部将每次请求的limit固定为常量MAX_LIMIT_ALLOWED_BY_API 100const MAX_LIMIT_ALLOWED_BY_API 100; while (true) { const params: PaginationParams { ...(cursor ! undefined { cursor }), limit: MAX_LIMIT_ALLOWED_BY_API, }; const response await fetchFn(params); allItems.push(...(response.items as ArrayItemType)); // Stop if theres no next cursor if (!response.next_cursor) { break; } cursor response.next_cursor; }注意这个100是 SDK 工具自身的请求上限即 SDK 单页最多向 API 索要 100 条而非 API 的承诺值。当某个端点如 Auth Config 列表将单页实际截断为 50 条时SDK 拿到的一页就是 50 条getAllPages会继续跟随next_cursor翻页直到取完——这正是端点级限制与SDK 通用翻页正确协作的方式。而在 Python SDK 侧tools.py 中 Tool Router 会话工具列表的拉取逻辑也采用完全相同的游标模式cursor: t.Optional[str] None while True: tools_response self._client.tool_router.session.tools( session_idsession_id, cursornone_to_omit(cursor), limitTOOL_ROUTER_SESSION_TOOLS_PAGE_LIMIT, ) tools_list.extend(_normalize_tool(item) for item in tools_response.items) cursor getattr(tools_response, next_cursor, None) if not cursor: break其中TOOL_ROUTER_SESSION_TOOLS_PAGE_LIMIT是 Tool Router 端点专属的页大小常量进一步印证了每个端点独立定义 limit的设计。二、Auth Config 列表每页最多 50 条必须游标翻页这是本知识库条目中最关键的实操结论GET /api/v3/auth_configs与GET /api/v3.1/auth_configs当前每页最多返回50条 Auth Config。对应端点可参考 API 参考文档 auth-configs/index.mdx 中的端点清单POST /api/v3.1/auth_configs、GET /api/v3.1/auth_configs、GET /api/v3.1/auth_configs/{nanoid}、PATCH、DELETE等其中 GET 列表即本条目讨论的 50 条上限端点。正确的翻页流程游标分页正确做法是读取每个响应中的next_cursor字段将其作为下一请求的cursor参数传入直到next_cursor为空。伪代码流程如下1. 请求 GET /api/v3/auth_configs?limit50或使用默认页大小 2. 处理响应中的 items 3. 若响应含 next_cursor 且非空 以 cursornext_cursor 发起下一次请求回到步骤 2 4. 若 next_cursor 为空或缺失 分页结束所有数据已取完REST 调用示例curl第一页curl -G https://backend.composio.dev/api/v3/auth_configs \ -H Authorization: Bearer $COMPOSIO_API_KEY \ -d limit50从响应中取出next_cursor继续翻页curl -G https://backend.composio.dev/api/v3/auth_configs \ -H Authorization: Bearer $COMPOSIO_API_KEY \ -d limit50 \ -d cursor上页响应中的 next_cursor重复上述请求直到某次响应中的next_cursor为空。三、SDK 层的分页封装你几乎不需要手写游标循环Python SDKPython SDK 的 Auth Config 模块在 auth-configs.mdx 参考文档 中暴露了list()方法返回AuthConfigListResponse用法见官方示例 examples/auth_configs.pyfrom composio import Composio composio Composio() # List all auth configs auth_configs composio.auth_configs.list() print(auth_configs)当配置数量超过 50 条时单次list()只会返回第一页你需要用返回结构中的next_cursor继续请求直至取完所有页。推荐封装一个循环from composio import Composio composio Composio() all_configs [] cursor None while True: page composio.auth_configs.list( query{cursor: cursor} if cursor else {} ) all_configs.extend(page.items) if not page.next_cursor: break cursor page.next_cursor print(f共拉取 {len(all_configs)} 条 auth config)TypeScript SDKTypeScript SDK 在 transformers/authConfigs.ts 中把 API 响应的next_cursor转换为 SDK 侧的nextCursor并透传total_pages因此 SDK 消费方看到的是驼峰命名的nextCursoritems: response.items.map(transformAuthConfigRetrieveResponse), nextCursor: response.next_cursor ?? null, totalPages: response.total_pages,对于取全部的场景推荐直接使用 SDK 内置的getAllPages工具pagination.ts它已自动处理next_cursor翻页与类型推导import { getAllPages } from composio/core/utils/pagination; import { composio } from ./client; // 自动翻页拉取全部 auth configs const allAuthConfigs await getAllPages((params) composio.authConfigs.list({ ...params }) );该工具的行为以limit: 100请求、依据next_cursor遍历、next_cursor为空即停止均有对应单元测试覆盖见 pagination.test.ts可作为理解其语义的参考。四、重要警示文档宣传上限 ≠ 线上实际上限知识库条目特别强调了一个容易踩坑的现实问题一些由系统生成的接口描述generated descriptions可能宣传更大的分页上限但已部署的端点仍会把每页截断为 50 条。这意味着不要依赖生成式文档中的 limit 描述来假设一次能取回多少条数据即使你请求limit100或更大Auth Config 端点实际返回的页大小仍可能被钳制在 50这种文档/运行时不一致应作为**产品缺陷product issue**上报处理而不是跳过游标分页的理由。正确的防御性写法永远是始终读取next_cursor并循环翻页。无论单页返回 50 条还是 100 条只要遵循游标循环结果都不会遗漏反之任何假设单页能装下全部数据的代码都会在数据量跨过阈值时静默丢失条目。五、分页实战自查清单结合本文内容给出在使用 Composio 列表类端点时建议遵循的检查清单检查项说明确认端点级限制在代码里写死 limit 前先核对对应端点的 OpenAPI schema 与线上行为不要假设全局页大小始终使用游标每个列表响应都要检查next_cursor/nextCursor非空则继续以cursor翻页区分 SDK 字段命名REST 响应为 snake_case 的next_cursorTS SDK 转换为 camelCase 的nextCursor容忍文档偏差生成式描述宣传的上限可能与线上不一致以线上实际返回为准并把偏差作为产品问题上报善用getAllPagesTS SDK 的getAllPages已封装完整翻页逻辑优先复用而非手写循环留意 Provider 传导Toolkit Actions 的分页还受上游第三方 Provider 规则影响跨界排查时需一并考虑六、小结Composio 的分页体系以端点级限制 游标翻页为核心没有全局统一的页大小Auth Config 列表端点当前每页上限 50 条其余端点目录、Tool Router、日志、计费等各自定义。开发者需要养成的习惯是——任何列表端点都按next_cursor游标循环消费并始终以线上实际返回为准。TS SDK 的getAllPages与 Python SDK 的list()都已围绕这一机制设计合理使用即可写出既健壮又不易漏数据的集成代码。【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考