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 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).
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.

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.

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.

{
  "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
}

{
  "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"
        }
      ]
    }
  }
}

// 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'

# 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 <...>.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "run-connector-action",
    "arguments": {
      "connector_id": "6aa0fc7d19a6e73abca9352d",
      "action": "search",
      "params": { "query": "Ada Lovelace" }
    }
  }
}

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"}}'

import { Fabric } from '@wexa-fabric/sdk'

const fabric = new Fabric()
const result = await fabric.runConnectorAction({
  connector_id: "6aa0fc7d19a6e73abca9352d",
  action: "search",
  params: { query: "Ada Lovelace" }
})

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. 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. 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.