Retrieve Agent Action Execution Status

Retrieve the status of an executed agent action. Requires at least one query parameter, execution_id or external_id, to identify the action.

GET/api/{version}/services/ai/agent_actions/status

Headers

Name	Description
`Accept`	`application/json` (default) or `application/xml`

Query Parameters

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

Name	Description
`execution_id` conditional	Required if `external_id` is not specified. The execution ID of the agent action. Returned as `executionId` from the Execute Agent Action request.
`external_id` conditional	Required if `execution_id` is not specified. The external ID of the agent action execution. Returned as `externalId` from the Execute Agent Action request.

Request

curl --location 'https://myvault.veevavault.com/api/v26.2/services/ai/agent_actions/status?execution_id=VAB000000003001' \
--header 'Accept: application/json' \
--header 'Authorization: {AUTH_VALUE}' \
--header 'X-VaultAPI-ClientID: veeva-vault-api-reference-example'

Response

{
   "responseStatus": "SUCCESS",
   "actionResponse": {
       "actionStatus": "SUCCESS",
       "executionId": "VAB000000003002",
       "agentAction": "quick_check__v.spelling_grammar__v",
       "actionOutputs": [
           {
               "type": "text",
               "value": "```json\n{\n  \"thinking\": \"Document Language: US English (confirmed by '$' symbol, MM/DD date format, 'color' spelling, and FDA-style regulatory language). Allowed Lexicon: Pharmaceutical (Human) / FDA / Patient-facing consumer content; accepting brand names (BenzaClin, Viscontour), medical terms (clindamycin, benzoyl peroxide, androgens, inflammatory acne), and creative fragments typical of patient brochures. Error Density: Moderate—primarily OCR artifacts (stray characters, malformed symbols) and a few genuine spelling/grammar issues (e.g., 'Cornrnon', 'Abqqt', missing space in 'acneheroes,com').\",\n  \"detected_industry\": \"Pharmaceutical (Human)\",\n  \"detected_regulatory_authority\": \"FDA\",\n  \"detected_target_audience\": \"Patient\",\n  \"errors\": [\n    {\n      \"page_number\": 2,\n      \"issue\": \"c1indamycin\",\n      \"error_type\": \"SpellingError\",\n      \"reason\": \"The numeral '1' is incorrectly used instead of the letter 'l'.\",\n      \"suggestion\": \"clindamycin\"\n    },\n    {\n      \"page_number\": 3,\n      \"issue\": \"Its\",\n      \"error_type\": \"GrammarError\",\n      \"reason\": \"Missing apostrophe; should be the contraction 'It's' (It is).\",\n      \"suggestion\": \"It's\"\n    } ] \n}```"
           }
       ]
   }
}

Response Details

On SUCCESS, the response returns the submitted execution ID and provides the status.

Name	Description
`actionStatus` conditional	The status of the action. For example, an action which is still in progress returns `IN_PROGRESS`. When complete, the value is `SUCCESS`.
`actionOutputs` conditional	For completed actions with an `actionStatus` of `SUCCESS`, this array contains the action's output. For example, the text returned to the user in Vault AI Chat.

Query Agent Response

When the agent is query_agent__sys and action is query_vault__sys, the action runs in non-interactive mode. The actionOutputs array contains two entries: a text entry with the Markdown summary as a plain string, and a json entry whose value is the structured result object described in the following response fields. When invoking the Query Agent via Vault AI MCP, the tool result is this structured object directly without the actionOutputs wrapper.

Response Fields

Name	Description
`status`	The outcome: `answered`: The query completed and results are available. `needs_postprocess`: Additional processing is required. `no_vql_question`: The input did not contain a queryable question. `failed`: The action did not complete.
`summary`	Concise Markdown summary of the answer for a non-technical user. Uses user-facing labels instead of API Names.
`confidence` optional	Confidence level of the answer. Values: `high`, `medium`, `low`.
`failure_reason` optional	Present when `status` is `failed`. Values: `budget_exhausted`, `unanswerable_by_available_schema`, `unresolved_required_context`, `vql_execution_rejected`, `other_errors`.
`vql_steps` optional	Array of executed VQL steps. Each entry contains the fields described in the `vql_steps` Fields section.

vql_steps Fields

Name	Description
`step`	The step number, as an integer.
`goal`	What this step's data represents.
`vql`	The VQL query that was executed.
`query_describe`	Object describing the query target and the fields in the `SELECT` clause. Contains: `object`: An object with `name` and `label` string properties. `fields`: An array of objects, each with `name` and `label` string properties. `label` is `null` for system fields with no display label.
`sample_rows` optional	Array of sample rows returned by the query. Each row is an object whose keys are field names and whose values may be strings, arrays (for fields processed by `TOLABEL()` or `TODISPLAYVALUE()`), or other JSON types. Present only for row-returning steps. Absent for count-only steps (`PAGESIZE 0`). Up to 200 rows in non-interactive mode and up to 20 rows in interactive mode.
`sample_rows_truncated` optional	`true` if the query returned more rows than the `sample_rows` cap. Present only when rows were truncated.
`row_count` optional	Present on count-only steps (`PAGESIZE 0`) and is `0`. Absent on row-returning steps.
`total_count`	The total number of rows matching the query. The maximum value is 1001. A value of 1001 indicates more than 1,000 rows exist.

Data Display

Query Agent automatically applies the following functions to SELECT fields before returning results:

TOLABEL() on object lifecycle fields (lifecycle__v), lifecycle state fields (state__v), picklist fields, and object type fields (object_type__v).
TODISPLAYVALUE() on object reference fields.
TODISPLAYFORMAT() on fields that have a defined format mask.

For document queries, Query Agent adds the following fields to SELECT if not already present, up to a total of 20 selected fields, with agent-selected fields taking precedence: document_number__v, name__v, type__v, subtype__v, classification__v, status__v, TODISPLAYVALUE(created_by__v), document_creation_date__v, TODISPLAYVALUE(last_modified_by__v), version_modified_date__v.

For object queries, Query Agent adds list layout fields for the queried object, up to a total of 20 selected fields.

Query Agent Response Example

{
    "responseStatus": "SUCCESS",
    "actionResponse": {
        "actionStatus": "SUCCESS",
        "executionId": "V8100000001G003",
        "agentAction": "query_agent__sys.query_vault__sys",
        "actionOutputs": [
            {
                "type": "text",
                "value": "**32 documents found.** ..."
            },
            {
                "type": "json",
                "value": {
                    "status": "answered",
                    "summary": "**32 documents found.** ...",
                    "vql_steps": [
                        {
                            "step": 1,
                            "goal": "Retrieve the name and lifecycle status of every document.",
                            "vql": "SELECT LATESTVERSION version_id, id, name__v, status__v FROM ALLVERSIONS documents",
                            "query_describe": {
                                "object": {
                                    "name": "documents",
                                    "label": "documents"
                                },
                                "fields": [
                                    { "name": "version_id", "label": null },
                                    { "name": "name__v", "label": "Name" },
                                    { "name": "status__v", "label": "Status" },
                                    { "name": "document_number__v", "label": "Document Number" }
                                ]
                            },
                            "total_count": 32,
                            "sample_rows": [
                                {
                                    "version_id": "4501_1_0",
                                    "id": "4501",
                                    "name__v": "Redacted - Full Patient Brochure",
                                    "status__v": ["Approved"],
                                    "document_number__v": "VV-00033",
                                    "type__v": ["General Documents"],
                                    "created_by__v": ["Jane Smith"],
                                    "document_creation_date__v": "2026-10-08T01:56:36Z"
                                }
                            ]
                        }
                    ]
                }
            }
        ]
    }
}