> Source: https://wexa.ai/docs/tools/run-connector-action # run-connector-action Run one action of a connector, and get its result back. Get the connector's id, the action's name and the JSON Schema of its `params` from [`list-connectors`](/docs/tools/list-connectors) first. The action runs the same way it runs when an agent uses the connector's skill: the same executor, with the connector's own credential. Before the action runs, the platform checks that you may use the connector. The rule is the one that decides what `list-connectors` shows you: the access scope chosen when the connector was provisioned. | Access scope | 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. Only an action that `list-connectors` lists for the connector can run. ## Which actions need approval 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 that decision: | The platform's decision for the action | What happens | | --- | --- | | Not gated | The action runs at once, unless the project's consequential-write gate holds it (see [Governance](#governance)). | | 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 row 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. Both SDKs already handle a pending approval. The TypeScript SDK raises `ApprovalRequired`, and the Python SDK raises `ApprovalRequired`; each carries 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. ## What it is called on each surface The wire name is `run-connector-action` everywhere: it is what the Wexa MCP server advertises, the REST path is `POST /v1/run-connector-action`, and each SDK exposes it under its own language's naming convention. | Surface | Name | | --- | --- | | Wexa MCP server | `run-connector-action` | | REST API | `POST /v1/run-connector-action` | | TypeScript SDK | `fabric.runConnectorAction()` | | Python SDK | `fabric.run_connector_action()` | ## Arguments | Argument | Type | Required | Notes | | --- | --- | --- | --- | | `action` | string | Required | The action's name, from the connector's actions in list-connectors. | | `connector_id` | string | Required | The connector, from list-connectors. | | `params` | object | Optional | The action's arguments, as its input_schema in list-connectors describes. | A `params` field that the action's `input_schema` marks as required must be present, or the call is refused before the action runs. `project_id`, `projectID`, `organization_id` and `executed_by` are not arguments you pass: the platform binds all four from the credential you authenticated with, and both SDKs refuse them before the request leaves your process — see [server-bound arguments](/docs/get-started/scope-and-server-bound-arguments). ## What it returns The result names the connector and the action, and `data` is what the action returned. The shape of `data` is the action's own. The three surfaces wrap this differently, and code written against one will not read another correctly — see [return shape](/docs/tools/overview#return-shape). 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 ``` Keeping the `lifecycle_id` is what lets you ask later why a call was allowed, refused or held. ## Calling it The same call on all four surfaces. Pick a tab once and every code block in the documentation follows it. The ids in this example are real, and resolve against the project the documentation is written against. Swap them for your own. A value in angle brackets is one only you can supply, and the platform refuses a literal `<...>`. **Call run-connector-action** **Wexa MCP server** ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "run-connector-action", "arguments": { "connector_id": "6aa0fc7d19a6e73abca9352d", "action": "search", "params": { "query": "Ada Lovelace" } } } } ``` **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"}}' ``` **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" } }) ``` **Python SDK** ```python from wexa import Fabric fabric = Fabric() out = fabric.run_connector_action( connector_id="6aa0fc7d19a6e73abca9352d", action="search", params={"query": "Ada Lovelace"}, ) ``` ## Errors Both SDKs raise the same typed errors, chosen from the gateway's own error string first and its HTTP status second. `run-connector-action` checks the `fabric:connector.run` grant, and reaches the seven classes every tool reaches — listed under [the common set](/docs/tools/errors#the-common-set). These are the ones specific to it: | Error | Status | Raised when | | --- | --- | --- | | `ForbiddenError` | 403 | The connector is not one your project may use (`S8:connector-not-usable`): it does not exist, it is in another organization, or its access scope does not include you. | | `NotFound` | 404 | The connector has no runnable action with that name (`S8:connector-action-not-available`). | | `ValidationError` | 422 | A `params` field that the action requires is missing. | | `UpstreamError` | 502 | The action ran and failed (`S8:connector-action-failed`). A failed action is never returned as a result. | | `TimeoutError` | 504 | The action did not finish in time (`S8:connector-action-timeout`). Its outcome is unknown: check the connected system before you run it again. | 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. ## Governance Every call to `run-connector-action` runs through the same ten-stage lifecycle as every other Wexa tool: the credential is resolved to a scope, the `fabric:connector.run` grant is checked, quota is drawn down, the arguments are validated, policy rules are evaluated, the call is executed, the result is shaped and redacted, and an audit record is written. The `lifecycle_id` in the response is the handle to that record. Every run also writes a `run-connector-action.run` audit event, whether the run succeeded, failed or was refused. The event records 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 itself 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. `run-connector-action` is marked consequential. 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 call returns `202` and an `ApprovalRequired` error carrying the approval id and a resume token. This gate is on by default for every project, admin API keys included. It is a breaking change for code that expected ungated actions to run at once. A project admin can turn the gate off, or back on, in the project's settings; with it off, approval is decided per action, as [described above](#which-actions-need-approval). Actions taken by a person in the console are not held by this gate. `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. ## See also [`list-connectors`](/docs/tools/list-connectors), [the tool index](/docs/tools/overview), [errors](/docs/tools/errors), and [which identifier goes where](/docs/tools/identifiers).