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

# Execute Agent Action

<Aside type="note">The functionality described on this page is only available to customers who have licensed Veeva AI.</Aside>
Execute the specified agent action. The authenticated user must have permission to execute the action.

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

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

## Headers {#headers}

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

## Body Parameters {#body-parameters}

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

<FieldTable>
| Name | Description |
| --- | --- |
| `agent_name` | The name of the agent to execute the action. Can be omitted if you are using `user_message` instead. |
| `action_name` | The name of the action to execute. Can be omitted if you are using `user_message` instead. |
| `user_message` | The message a Vault user sent to Veeva AI Chat. Required if `agent_name` and `action_name` are omitted. |
| `document_id` | 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` | Required if the agent is scoped to objects: The name of the object. |
| `objecttype` | Required if the agent is scoped to objects: The name of the object type. |
| `record_id` | Required if the agent is scoped to objects: The ID of the object record. |
| `chat_id` | The chat ID of an existing Veeva AI Chat. |
| `external_id` | 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 {#request}

<CodeExample title="">
```
curl --location 'https://myvault.veevavault.com/api/v26.1/services/ai/agent_actions/actions/execute' \
--header 'Authorization: {SESSION_ID}' \
--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 {#response}

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

```
</CodeExample>

## Response Details {#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](/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](/ai-agents/api/retrieve-agent-action)  
**Next:** [Cancel Agent Action Execution](/ai-agents/api/cancel-agent-action-execution)