POST
/
api
/
v2
/
ai-actions
/
{ai_action_id}
/
execute
/
Execute Stored AI Action
curl --request POST \
  --url https://actions.zapier.com/api/v2/ai-actions/{ai_action_id}/execute/ \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "instructions": "<string>",
  "params": {}
}'
{
  "execution_log_id": "<string>",
  "action_used": "<string>",
  "input_params": {},
  "resolved_params": {},
  "results": [
    {}
  ],
  "full_results": [
    {}
  ],
  "result_field_labels": {},
  "status": "success",
  "error": "<string>"
}

Authorizations

​
x-api-key
string
header
required

Path Parameters

​
ai_action_id
string
required

The ID of the action to execute.

Query Parameters

​
preview_only
boolean
default:false

Body

application/json

Specifies information about how to run an AI Action

​
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"

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

Response

OK

​
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
Results · object[] | null

Results of the action after it ran.

This will be an empty list if preview_only is true.

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