POST
/
api
/
v2
/
execute
/

See params_constraints in the documentation below for details on how to tell the AI which values to use and which to guess when running the action.

See Get action details and needs for how to discover the needs for an action.

Authorizations

x-api-key
string
headerrequired

Query Parameters

provider_id
string

Provider ID for AI Actions. If you don't know what your provider ID is, please contact support

token_budget
integer
default: 1000

DEPRECATED: This field is kept temporarily for compatibility. Maximum number of tokens to use for each field.

When this limit is exceeded in the response from the execution, values will be truncated to fit inside of it.

If this is increased too much, running an action may fail if its results get outside of the context window of the LLM.

preview_only
boolean
default: false

If this is true, then the action will not actually be executed and instead the resolved params will come back.

skip_param_guessing
boolean
default: false

If set to True, AI Actions will make a direct invocation call without attempting to guess params.

When skip_param_guessing is True, all params must be set to either 'locked' or 'ignored' mode. Otherwise, an error will be raised.

Note: skip_param_guessing is mutually exclusive with preview_only. When skip_param_guessing is True, preview_only must be False, and vice versa.

Body

application/json
instructions
string
required

instructions should be plain English instructions about how to run the action

For example, "Send a message with a joke about pirates delivering pizza to the #general Slack channel"

app
string
required

The app to use (i.e. SlackAPI or GoogleSheetsV2API).

From the Search Apps or Search Actions endpoint.

action
string
required

The action to run (i.e. direct_message or add_row).

From the App Details or Search Actions endpoint.

params
object

params can be used to give AI Actions specific values, or hints for how to guess values.

Inside of the params object, each key should be the key of a specific need.

Inside of the value for each need, you can set a mode and a value.

"mode": "locked"

A mode of locked means that when running the action, AI Actions will use the exact value provided inside of value.

This is useful when the user has selected a specific value for a prefill, or has entered a specific value like a string.

For example, if you know ahead of time the exact ID of a Slack channel that you want to send a message to and you're using the SlackAPI's channel_message action:

{
    "params": {
        "channel": {
            "mode": "locked",
            "value": "CHANNEL_ID"
        }
    }
}

"mode": "guess"

When using a mode of guess, AI Actions will use the value to try and figure out what to use for the need.

This is useful when you only have a text description of a need's value, but don't know its actual ID.

For example, if you provide the following for the SlackAPI API's channel_message action:

{
    "params": {
        "channel": {
            "mode": "guess",
            "value": "#general"
        }
    }
}

Behind the scenes, when AI Actions runs the action it will look through all of the available fields for the channel prefill (the same list you would get from the Get Prefill Choices endpoint) and choose the one that best semantically matches the value provided.

"mode": "choose_from"

When using a mode of choose_from, the value must be a list of values to choose from.

The values must be an array of exact IDs from the Get Prefill Choices endpoint.

Using an array of values is useful if the user wants to choose from i.e. a list of Slack channels that they want to send a message to based on the instructions.

For example,

{
    "params": {
        "channel": {
            "mode": "guess",
            "value": ["CHANNEL_ID", "ANOTHER_CHANNEL_ID"]
        }
    }
}

Behind the scenes, when AI Actions goes to run the action it will look up the label of the provided IDs and choose th one that makes the most sense based off of the provided instructions.

action_type
enum<string>
default: write

The type of the action to run (most likely write or search).

From the App Details or Search Actions endpoint.

Available options:
read,
write,
search,
read_bulk
authentication_id
integer | null

The authentication to use for the app.

From the List Authentications for App endpoint.

account_id
integer | null

Zapier account ID to use when running the action.

Some Zapier users may have multiple accounts under the same Zapier user.

If no account_id is provided here, then the account that they're currently logged into on Zapier.com will be the one that is used when running the action.

Response

200 - application/json
execution_log_id
string
required

ID of the execution log.

This can be used with the Rate Execution Log endpoint to give feedback on the execution.

We frequently monitor this feedback!

action_used
string
required

The name of the action that was executed.

input_params
object
required

The parameters that were passed into the API.

resolved_params
object | null

The resolved parameters for the action.

If preview_only is true, this will be the parameters that the AI would have used to run the action if it were not a preview. If preview_only is false, these are the parameters that the AI used to run the action.

results
object[] | null

Results of the action after it ran.

This will be an empty list if preview_only is true.

full_results
object[] | null

DEPRECATED: Use results instead. This field is kept temporarily for compatibility.

result_field_labels
object | null

Human readable labels for some of the keys in the result.

status
enum<string>
default: success

The status of the execution.

  • success: The action was executed successfully.
  • error: The action failed to execute, see error field.
  • empty: The action was not executed.
  • preview: The action was previewed.
Available options:
success,
error,
empty,
preview
error
string | null

The error message if the execution failed.

Stateless actions introductionIntroduction