> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns. > > **Recommended**: > ```bash > npx @scalekit-inc/cli setup > ``` > > Global: > ```bash > npm install -g @scalekit-inc/cli > scalekit setup > ``` > > Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents. > Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim. > [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/) --- # List a user's scoped tools (beta) `GET /api/v1/tools/scoped` This endpoint is in beta. Its request and response may change. Tools already bound to one connected-account identifier. Use this when you need the list a user or agent is authorized to call (the list you pass to an LLM). `identifier` is required, and so is at least one `filter.*` field (provider, tool name or connection name): without one the API returns `INVALID_ARGUMENT`. **Query parameters** | Name | Type | Required | Description | | --- | --- | --- | --- | | `identifier` | string | Yes | Your app's ID for the user, the same value you used when the user connected. Use a stable internal ID, not an email address. | | `filter.connection_names` | array of string | No | Filter by one or more connection names. | | `filter.providers` | array of string | No | Filter by one or more tool providers. | | `filter.tool_names` | array of string | No | Filter by one or more tool names. | | `page_size` | integer | No | Maximum number of tools to return per page. | | `page_token` | string | No | Token from a previous response for pagination. | **Response (200)** | Name | Type | Description | | --- | --- | --- | | `next_page_token` | string | Token for fetching the next page of tools. | | `prev_page_token` | string | Token for fetching the previous page of tools. | | `tools` | array of object | List of tools scoped to the given connected account identifier. | | `tools.connected_account_id` | string | ID of the connected account for this scoped tool. | | `tools.identifier` | string | Your app's ID for the user, the value passed when the account was created. | | `tools.tool` | object | The underlying tool definition. | | `tools.tool.definition` | object | Tool definition in structured format. | | `tools.tool.id` | string | Unique ID of the tool. Immutable and read-only. | | `tools.tool.is_default` | boolean | Marks this tool as the default version for the combination. Read-only. | | `tools.tool.metadata` | object | Additional metadata about the tool. | | `tools.tool.provider` | string | Provider name (e.g. GOOGLE). Read-only. | | `tools.tool.tags` | array of string | Tags for categorization or filtering. | | `tools.tool.updated_at` | string | Timestamp when the tool was last updated. Read-only. | | `total_size` | integer | Total number of tools matching the query. | **Errors** - `400`: Invalid request - missing identifier or malformed filter/pagination parameters - `401`: Authentication required - missing or invalid access token **Request** ```bash curl -sS -G -X GET \ "$SCALEKIT_ENVIRONMENT_URL/api/v1/tools/scoped" \ -H "Authorization: Bearer $TOKEN" \ --data-urlencode "identifier=user_123" \ --data-urlencode "filter.connection_names=gmail" \ --data-urlencode "page_size=2" ``` **Response** ```json { "tools": [ { "connected_account_id": "ca_24834495392086178", "identifier": "user_123", "tool": { "id": "tol_86147403291582051", "provider": "GMAIL", "definition": { "name": "gmail_fetch_mails", "description": "Fetch emails from a connected Gmail account using search filters. Requires a valid Gmail OAuth2 connection.", "schema_version": "1", "tool_version": "1", "input_schema": { "type": "object", "properties": { "query": { "type": [ "string", "null" ], "description": "Search query string using Gmail's search syntax (e.g., 'is:unread from:user@example.com')" }, "max_results": { "type": [ "integer", "null" ], "description": "Maximum number of emails to fetch" } } } }, "is_default": true, "metadata": {}, "tags": [] } }, { "connected_account_id": "ca_24834495392086178", "identifier": "user_123", "tool": { "id": "tol_86147403291583327", "provider": "GMAIL", "definition": { "name": "gmail_send_message", "description": "Send an email message immediately from the authenticated Gmail account. Constructs a MIME message and sends it via the Gmail API.", "schema_version": "1", "tool_version": "1", "input_schema": { "type": "object", "properties": { "to": { "type": "string", "description": "The recipient email address(es) for the message." }, "subject": { "type": "string", "description": "The subject line of the email." }, "body": { "type": "string", "description": "The body content of the email." } }, "required": [ "to", "subject", "body" ] } }, "is_default": true, "metadata": {}, "tags": [] } } ], "next_page_token": "eyJhZnRlciI6InRvbF84NjE0NzQwMzI5MTU4MzMyNyJ9", "prev_page_token": "", "total_size": 48 } ``` **Python SDK:** `scalekit_client.tools.list_scoped_tools` Lists the tools a user can call, narrowed by the filter. ```python scalekit_client.tools.list_scoped_tools( identifier: str, filter: Optional[ScopedToolFilter] = None, page_size: Optional[int] = None, page_token: Optional[str] = None, ) -> Tuple[ListScopedToolsResponse, grpc.Call] ``` Example: ```python page, _ = scalekit_client.tools.list_scoped_tools( identifier="user_123", filter={"connection_names": ["gmail"]}, page_size=2, ) ``` | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `identifier` | `str` | Yes | Your app's ID for the user, the same value you used when the user connected. Use a stable internal ID, not an email address. | | `filter` | `Optional[ScopedToolFilter]` | Yes | Filter parameters for scoped tools | | `page_size` | `Optional[int]` | No | Maximum number of tools to return per page | | `page_token` | `Optional[str]` | No | Token from a previous response for pagination | Returns `Tuple[ListScopedToolsResponse, grpc.Call]`: The response and the gRPC call. Unpack it as `page, _ = ...`. **Node.js SDK:** `scalekit.tools.listScopedTools` Lists tools that are scoped to a specific connected account identifier. ```ts scalekit.tools.listScopedTools( identifier: string, options: { filter: MessageInitShape; pageSize?: number; pageToken?: string; }, ): Promise ``` Example: ```ts const result = await scalekit.tools.listScopedTools("user_123", { filter: { connectionNames: ["gmail"] }, pageSize: 2, }); ``` | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `identifier` | `string` | Yes | Your app's ID for the user, the same value you used when the user connected. Use a stable internal ID, not an email address. | | `filter` | `MessageInitShape` | Yes | Filter configuration for scoped tools (providers, tool names, connection names). Required. | | `pageSize` | `number` | No | Maximum number of tools to return per page. | | `pageToken` | `string` | No | Token from a previous `listScopedTools` response for pagination. | Returns `Promise`. **Used in** - [Anthropic](https://docs.scalekit.com/agentkit/examples/anthropic/) - [Call your connector](https://docs.scalekit.com/agentkit/bring-your-own-connector/making-tool-calls/) - [FastRouter + Scalekit tool calling](https://docs.scalekit.com/cookbooks/fastrouter-agentkit-tool-calling/) - [Migrate from Composio to Scalekit](https://docs.scalekit.com/agentkit/advanced/migrate-from-composio/) - [OpenAI](https://docs.scalekit.com/agentkit/examples/openai/) - [Use built-in tools](https://docs.scalekit.com/agentkit/tools/scalekit-optimized-tools/) - [Vercel AI SDK](https://docs.scalekit.com/agentkit/examples/vercel-ai/) Part of [Tools](https://docs.scalekit.com/agentkit/reference/tools/) in the [AgentKit API reference](https://docs.scalekit.com/agentkit/reference/). Authentication: https://docs.scalekit.com/agentkit/reference/authentication.md. Errors and rate limits: https://docs.scalekit.com/agentkit/reference/errors.md. Pagination: https://docs.scalekit.com/agentkit/reference/pagination.md --- ## More Scalekit documentation | Resource | What it contains | When to use it | |----------|-----------------|----------------| | [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content | | [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas | | [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |