> Source: https://wexa.ai/docs/connectors/run-connector-action # run-connector-action [Can be held for approval](/docs/sdks-and-apis/how-every-tool-call-works#lifecycle-and-governance) Run one action of a connector, and get its result back. It runs the way an agent's skill does, with the connector's own credential. Get the connector id, the action name and the JSON Schema of `params` from [`list-connectors`](/docs/connectors/list-connectors) first. Needs the `fabric:connector.run` grant. **Run a connector action** **Wexa MCP server** ```bash curl -sS -X POST https://fabric.wexa.ai/mcp/$FABRIC_PROJECT_ID \ -H "authorization: Bearer $FABRIC_API_KEY" \ -H "Mcp-Session-Id: $MCP_SESSION_ID" \ -H "content-type: application/json" -H "accept: application/json" \ -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"run-connector-action","arguments":{"connector_id":"6aa0fc7d19a6e73abca9352d","action":"search","params":{"query":"Ada Lovelace"}}}}' ``` ```json { "content": [ { "type": "text", "text": "{\"lifecycle_id\":\"qlc_000025\",\"result\":{\"action\":\"search\",\"connector_id\":\"6aa0fc7d19a6e73abca9352d\",\"data\":{\"abstract_url\":\"https://en.wikipedia.org/wiki/Ada_Lovelace\",\"heading\":\"Ada Lovelace\",\"results\":[{\"description\":null,\"title\":\"Ai-Da – humanoid robot, completed in 2019.\",\"url\":\"https://duckduckgo.com/Ai-Da\"}]}}}" } ], "isError": false } ``` **REST API** ```bash curl -sS https://fabric.wexa.ai/v1/run-connector-action \ -H "authorization: Bearer $FABRIC_API_KEY" \ -H "content-type: application/json" \ -d '{"connector_id":"6aa0fc7d19a6e73abca9352d","action":"search","params":{"query":"Ada Lovelace"}}' ``` ```json { "lifecycle_id": "qlc_000025", "result": { "action": "search", "connector_id": "6aa0fc7d19a6e73abca9352d", "data": { "abstract_url": "https://en.wikipedia.org/wiki/Ada_Lovelace", "heading": "Ada Lovelace", "results": [ { "description": null, "title": "Ai-Da – humanoid robot, completed in 2019.", "url": "https://duckduckgo.com/Ai-Da" } ] } } } ``` **TypeScript SDK** ```ts import { Fabric } from '@wexa-fabric/sdk' const fabric = new Fabric() const result = await fabric.runConnectorAction({ connector_id: '6aa0fc7d19a6e73abca9352d', action: 'search', params: { query: 'Ada Lovelace' } }) ``` ```ts // result is the payload itself, with no `.result` to read { action: 'search', connector_id: '6aa0fc7d19a6e73abca9352d', data: { abstract_url: 'https://en.wikipedia.org/wiki/Ada_Lovelace', heading: 'Ada Lovelace', results: [ { description: null, title: 'Ai-Da – humanoid robot, completed in 2019.', url: 'https://duckduckgo.com/Ai-Da' } ] } } ``` **Python SDK** ```python from wexa import Fabric fabric = Fabric() out = fabric.run_connector_action( connector_id="6aa0fc7d19a6e73abca9352d", action="search", params={ "query": "Ada Lovelace" }, ) ``` ```python # out is the result, already unwrapped { "action": "search", "connector_id": "6aa0fc7d19a6e73abca9352d", "data": { "abstract_url": "https://en.wikipedia.org/wiki/Ada_Lovelace", "heading": "Ada Lovelace", "results": [ { "description": None, "title": "Ai-Da – humanoid robot, completed in 2019.", "url": "https://duckduckgo.com/Ai-Da" } ] } } ``` ## Parameters | Parameter | Type | Required | Notes | | --- | --- | --- | --- | | `action` | string | Required | The action's name, from the connector's actions in `list-connectors`. Only an action listed there can run; one the connector lacks is refused (404). | | `connector_id` | string | Required | The connector, from `list-connectors`. Your project must be allowed to use it; one it may not use (unknown, in another organization, or outside the access scope) is refused (403). | | `params` | object | Optional | The action's arguments, as its `input_schema` in `list-connectors` describes. A field the schema marks as required must be present, or the call is refused before the action runs. | **Errors** - `ConflictError` (409): the connector has no usable stored credentials. The message names the connector and how to reconnect it; the connector stops reporting `ready` until it is reconnected. Retrying does not help. - `UpstreamError` (503): the credential store could not be read. Nothing was run and the connector is unchanged; try again shortly. - `UpstreamError` (502): the action ran and failed. A failed action is never returned as a result. - `TimeoutError` (504): the action did not finish in time. Its outcome is unknown: check the connected system before you run it again. **Show full response** The result names the connector and the action, and `data` is what the action returned. The shape of `data` is the action's own. A real response, captured from a live call to `run-connector-action` that ran DuckDuckGo's `search`. `results` is cut to its first entry of 10 to keep the page short; nothing else is changed. **Result of run-connector-action** **REST API** ```json { "lifecycle_id": "qlc_000025", "result": { "action": "search", "connector_id": "6aa0fc7d19a6e73abca9352d", "data": { "abstract_text": "Augusta Ada King, Countess of Lovelace, also known as Ada Lovelace, was an English mathematician and writer chiefly known for work on Charles Babbage's proposed mechanical general-purpose computer, the analytical engine. She was the first to recognise the machine had applications beyond pure calculation. Lovelace is often considered the first computer programmer. Lovelace was the only legitimate child of poet Lord Byron and reformer Anne Isabella Milbanke. Lord Byron separated from his wife a month after Ada was born, and died when she was eight. Although often ill in childhood, Lovelace pursued her studies assiduously. She married William King in 1835. King was a Baron, and was created Viscount Ockham and 1st Earl of Lovelace in 1838. The name Lovelace was chosen because Ada was descended from the extinct Baron Lovelaces. The title given to her husband thus made Ada the Countess of Lovelace.", "abstract_url": "https://en.wikipedia.org/wiki/Ada_Lovelace", "heading": "Ada Lovelace", "related_topics": [ { "first_url": "https://duckduckgo.com/Ai-Da", "icon": { "Height": "", "URL": "", "Width": "" }, "text": "Ai-Da – humanoid robot, completed in 2019." } ], "results": [ { "description": null, "title": "Ai-Da – humanoid robot, completed in 2019.", "url": "https://duckduckgo.com/Ai-Da" } ] } } } ``` **Wexa MCP server** ```json { "content": [ { "type": "text", "text": "{\"lifecycle_id\":\"qlc_000025\",\"result\":{\"action\":\"search\",\"connector_id\":\"6aa0fc7d19a6e73abca9352d\",\"data\":{\"abstract_text\":\"Augusta Ada King, Countess of Lovelace, also known as Ada Lovelace, was an English mathematician and writer chiefly known for work on Charles Babbage's proposed mechanical general-purpose computer, the analytical engine. She was the first to recognise the machine had applications beyond pure calculation. Lovelace is often considered the first computer programmer. Lovelace was the only legitimate child of poet Lord Byron and reformer Anne Isabella Milbanke. Lord Byron separated from his wife a month after Ada was born, and died when she was eight. Although often ill in childhood, Lovelace pursued her studies assiduously. She married William King in 1835. King was a Baron, and was created Viscount Ockham and 1st Earl of Lovelace in 1838. The name Lovelace was chosen because Ada was descended from the extinct Baron Lovelaces. The title given to her husband thus made Ada the Countess of Lovelace.\",\"abstract_url\":\"https://en.wikipedia.org/wiki/Ada_Lovelace\",\"heading\":\"Ada Lovelace\",\"related_topics\":[{\"first_url\":\"https://duckduckgo.com/Ai-Da\",\"icon\":{\"Height\":\"\",\"URL\":\"\",\"Width\":\"\"},\"text\":\"Ai-Da – humanoid robot, completed in 2019.\"}],\"results\":[{\"description\":null,\"title\":\"Ai-Da – humanoid robot, completed in 2019.\",\"url\":\"https://duckduckgo.com/Ai-Da\"}]}}}" } ], "isError": false } ``` **TypeScript SDK** ```ts // the object you get back IS the result — there is no `.result` to read { "action": "search", "connector_id": "6aa0fc7d19a6e73abca9352d", "data": { "abstract_text": "Augusta Ada King, Countess of Lovelace, also known as Ada Lovelace, was an English mathematician and writer chiefly known for work on Charles Babbage's proposed mechanical general-purpose computer, the analytical engine. She was the first to recognise the machine had applications beyond pure calculation. Lovelace is often considered the first computer programmer. Lovelace was the only legitimate child of poet Lord Byron and reformer Anne Isabella Milbanke. Lord Byron separated from his wife a month after Ada was born, and died when she was eight. Although often ill in childhood, Lovelace pursued her studies assiduously. She married William King in 1835. King was a Baron, and was created Viscount Ockham and 1st Earl of Lovelace in 1838. The name Lovelace was chosen because Ada was descended from the extinct Baron Lovelaces. The title given to her husband thus made Ada the Countess of Lovelace.", "abstract_url": "https://en.wikipedia.org/wiki/Ada_Lovelace", "heading": "Ada Lovelace", "related_topics": [ { "first_url": "https://duckduckgo.com/Ai-Da", "icon": { "Height": "", "URL": "", "Width": "" }, "text": "Ai-Da – humanoid robot, completed in 2019." } ], "results": [ { "description": null, "title": "Ai-Da – humanoid robot, completed in 2019.", "url": "https://duckduckgo.com/Ai-Da" } ] } } // The TS SDK names these camelCase — lifecycleId, traceId — where Python uses // lifecycle_id and trace_id. Both are non-enumerable: readable, but omitted by // Object.keys() and JSON.stringify(). `result.lifecycleId` here is undefined. result.lifecycleId // 'qlc_000025' ``` **Python SDK** ```python # a dict subclass; `result` is already unwrapped { "action": "search", "connector_id": "6aa0fc7d19a6e73abca9352d", "data": { "abstract_text": "Augusta Ada King, Countess of Lovelace, also known as Ada Lovelace, was an English mathematician and writer chiefly known for work on Charles Babbage's proposed mechanical general-purpose computer, the analytical engine. She was the first to recognise the machine had applications beyond pure calculation. Lovelace is often considered the first computer programmer. Lovelace was the only legitimate child of poet Lord Byron and reformer Anne Isabella Milbanke. Lord Byron separated from his wife a month after Ada was born, and died when she was eight. Although often ill in childhood, Lovelace pursued her studies assiduously. She married William King in 1835. King was a Baron, and was created Viscount Ockham and 1st Earl of Lovelace in 1838. The name Lovelace was chosen because Ada was descended from the extinct Baron Lovelaces. The title given to her husband thus made Ada the Countess of Lovelace.", "abstract_url": "https://en.wikipedia.org/wiki/Ada_Lovelace", "heading": "Ada Lovelace", "related_topics": [ { "first_url": "https://duckduckgo.com/Ai-Da", "icon": { "Height": "", "URL": "", "Width": "" }, "text": "Ai-Da – humanoid robot, completed in 2019." } ], "results": [ { "description": None, "title": "Ai-Da – humanoid robot, completed in 2019.", "url": "https://duckduckgo.com/Ai-Da" } ] } } out.lifecycle_id # 'qlc_000025' — an attribute, not a key ``` **More details** The platform checks that you may use the connector before the action runs. The rule is the one that decides what `list-connectors` shows you, the access scope chosen when the connector was provisioned. The action runs when: - `organization`: your project is in the connector's organization. - `department`: your project is in the connector's department. - `project`: your project is the project the connector was provisioned in. - `individual`: you are the person who provisioned it. A connector in another organization is always refused. The error codes are `S8:connector-not-usable` (`ForbiddenError`), `S8:connector-action-not-available` (`NotFound`), `S8:connector-action-failed` (`UpstreamError`) and `S8:connector-action-timeout` (`TimeoutError`; `TimeoutError_` in Python). An error that the action itself reports, for example a 400 for input the connected system does not accept, is passed through with its own status. Do not pass `retry: true` for an action that writes: a timeout does not tell you whether the write happened. Some actions do not run at once. The call returns a pending approval, and the action runs only after a person approves it. The platform already has a decision for each action of a provisioned connector, and this tool follows it: - Not gated: the action runs at once, unless the project turned on its consequential-write gate. - Gated (high risk, marked as requiring approval, or matched by a gate an administrator configured): the call returns a pending approval. - No decision exists for the action: the call returns a pending approval. The last case is deliberate. When the platform cannot confirm that an action is safe to run without a person, the action waits for one. An action can write to a customer's system with the connector's own credential, and an approval is easier to give than a wrong write is to undo. By default only High-risk actions are gated: actions that move money, change access, destroy at scale or act in bulk. Ordinary creates, updates and deletes are Medium and run at once. An admin can add or exempt actions with approval gates; see [managing approvals from the SDK](/docs/governance/policy-and-approvals#define-an-approval-gate). Both SDKs raise `ApprovalRequired` for a pending approval, carrying an approval id and a resume token. When a person approves, call the tool again with the resume token (`resume` in both SDKs), and the action runs with the arguments that were approved. When a person rejects, the resume is refused and the action never runs. Marked consequential. When the project's write gate is on, a call made with an API key or an SDK session waits for a person to approve it, whatever the platform's decision for the action. The gate is off by default; a project admin can turn it on, or back off, in the project's settings, and it then holds admin API keys too. Actions taken by a person in the console are not held by this gate. Every run also writes a `run-connector-action.run` audit event, whether the run succeeded, failed or was refused: who called, the connector and the action, the names of the `params` (not their values), the connector's access scope, your department, and whether the run needed approval. The approval is recorded next to it: `run-connector-action.approval.requested`, then `approval.approved` or `approval.rejected`, then `run-connector-action.approval.redeemed` when the approved run is resumed. `fabric:connector.run` is a separate grant. An API key minted before the grant existed does not carry it, and must be reissued to use this tool. Every tool call works the same way: [How every tool call works](/docs/sdks-and-apis/how-every-tool-call-works).