**Source URL:** https://limited.veevavault.dev/commercial/ai-agents/api/execute-agent-action

# Execute Agent Action

<Aside type="note">
The functionality described on this page is only available to customers who have licensed Vault AI.
</Aside>

Execute the specified agent action. This endpoint does not execute agent actions that have *API Access* set to *false*. The authenticated user must have permission to execute the action.

Before executing an action, you must [retrieve the parameters](/commercial/ai-agents/api/retrieve-agent-action/) required to run the action. After execution, you can [poll the status of the action](/commercial/ai-agents/api/retrieve-agent-action-execution-status/) and retrieve the output.

<Endpoint path="/api/{version}/services/ai/agent_actions/actions/execute" method="POST" />

## Headers

<FieldTable>
| Name | Description |
| --- | --- |
| `Accept` | `application/json` (default) or `application/xml` |
| `Content-Type` | `application/json` |
</FieldTable>

## Body Parameters

In the body of the request, include a JSON object with the following:

<FieldTable>
| Name | Description |
| --- | --- |
| `agent_name`<Requiredness type="conditional" /> | The name of the agent to execute the action. Can be omitted if you are using `user_message` instead. |
| `action_name`<Requiredness type="conditional" /> | The name of the action to execute. Can be omitted if you are using `user_message` instead. |
| `user_message`<Requiredness type="conditional" /> | The message a Vault user sent to Vault AI Chat. Required if `agent_name` and `action_name` are omitted. |
| `document_id`<Requiredness type="conditional" /> | Required if the agent is scoped to documents: The ID of the document, in the format `{id}` or `{id}_{major}_{minor}`. For example, `123` or `123_0_1`. If specifying a document ID without a version, performs the action on the latest version of the document that the authenticated user has access to. If specifying a document ID with a major and minor version, performs the action on the specified version. |
| `object`<Requiredness type="conditional" /> | Required if the agent is scoped to objects: The name of the object. |
| `objecttype`<Requiredness type="conditional" /> | Required if the agent is scoped to objects: The name of the object type. |
| `record_id`<Requiredness type="conditional" /> | Required if the agent is scoped to objects: The ID of the object record. |
| `chat_id`<Requiredness type="optional" /> | The chat ID of an existing Vault AI Chat. |
| `external_id`<Requiredness type="optional" /> | Identify this request with an external ID. Must be unique across executed actions. Vault will fail to execute an action if the `external_id` is the same as an in-progress or past action execution. |
</FieldTable>

## Request

<CodeExample title="">
```bash
curl --location 'https://myvault.veevavault.com/api/v26.1/services/ai/agent_actions/actions/execute' \
--header 'Authorization: {AUTH_VALUE}' \
--header 'Accept: application/json' \
--header 'X-VaultAPI-ClientID: veeva-vault-api-reference-example' \
--header 'Content-Type: application/json' \
--data '    {
        "agent_name": "quick_check__v",
        "action_name": "spelling_grammar__v",
        "document_id": "1234"
    }'
```
</CodeExample>

## Response

<CodeExample title="">
```json
{
    "responseStatus": "SUCCESS",
    "actionResponse": {
        "actionStatus": "IN_PROGRESS",
        "executionId": "VAB000000001001",
        "urls": [
            "/api/v26.1/services/ai/agent_actions/status?execution_id=VAB000000001001"
        ]
    }
}
```
</CodeExample>

## Response Details

On `SUCCESS`, the response contains the executing action's status, the execution ID, and provides a URL to the [Retrieve Agent Action Execution Status](/commercial/ai-agents/api/retrieve-agent-action-execution-status/) endpoint, which will provide the action's output when the action is complete.

---

**Previous:** [Retrieve Agent Action](/commercial/ai-agents/api/retrieve-agent-action)  
**Next:** [Cancel Agent Action Execution](/commercial/ai-agents/api/cancel-agent-action-execution)