# Notification Payload Formats

## [Dataset events](/automation-overview/triggers/notification-triggers.md#dataset-events)

```json
{
    project=<project-id>,
    type="dataset_version_created",
    title="Dataset version created: <new-version-name>",
    body="New dataset version <new-version-name> was created",
    data={
        "dataset": {
            "name": <dataset-name>,
            "id": <dataset-id>,
            "tags": [<dataset-tags>],
        },
        "version": {
            "id": <new-version-id>,
            "name": <new-version-name>,
            "uri": "dataset://<dataset-name>/<new-version-name>",
            "created_by": <username>,
            "tags": [<version-tags>],
        },
    },
}
```

## [Datum Alias events](/automation-overview/triggers/notification-triggers.md#datum-alias-events)

```json
{
  "project": <project-id>,
  "title": "Datum Alias Updated: <alias>'s datum is now updated to <new-file-name>",
  "type": "datum_alias_updated",
  "body": "Datum Alias <alias> is now pointing to <new-file-name>.",
  "url": "",
  "data": {
    "old_alias": {
      "name": "<alias>",
      "datum": <previous-file-name>,
      "updated_by": <user>
    },
    "updated_alias": {
      "name": <alias>,
      "datum": <new-file-name>,
      "updated_by": <user>
    }
  }
}

```

## [Model events](/automation-overview/triggers/notification-triggers.md#model-events)

```json
{
  "project": <project-id>,
  "title": <notification-title>,
  "type": <notification-type>,
  "body": <notification-body>,
  "url": "",
  "data": {
    "model": {
      "name": <model-name>,
      "id": <model-id>.,
      "slug": <model-slug>,
      "tags": [<model-tags>]
    },
    "model_version": {
      "id": <version-id>,
      "counter": <version-counter>,
      "uri": "model://<model-name>/<version-counter>",
      "created_by": <username>,
      "status": "<creating | pending | approved | rejected>",
      "tags": [<version-tags>]
    },
    "dataset_version": {
      "id": <dataset-version-id>,
      "name": <dataset-version-name>,
      "uri": "dataset://Model Dataset for <model-name>/model-<unique-id>",
      "created_by": <username>,
      "tags": [<tags>]
    }
  }
}
```

Variations based on the notification type:

* **Model version created**

  ```json
  {
      ...
      "title": "Model Version Created: <model-version>/<version-counter>",
      "type": "model_version_created",
      "body": "New model version <model-version>/<version-counter> has been created.",
      ...
  }
  ```
* **Model version status change**

  ```json
  {
    ...
    "title": "Model Version <Rejected | Approved>: <model-version>/<version-counter>",
    "type": "model_version_status_change",
    "body": "Model version <model-version>/<version-counter> has become <Rejected | Approved>.\n\n    The status was previously <Rejected | Approved>.",
    ...
    "data": {
      "model_version": {
        ...
        "previous_status": "<approved | rejected>"
      },
    },
    ...
  }
  ```
* **Model latest approved version change**

  ```json
  {
      ...
      "title": "Model <model-version> latest approved version has changed: <model-version>/<version-counter>",
      "type": "model_latest_approved_version_change",
      "body": "Model version <model-version>/<version-counter> has become the latest approved version. Version <version-counter> is now the only approved version.",
      ...
      "data": {
          ...
          "reason": "Version <version-counter> is now the only approved version."
      }
  }
  ```
* **Model version tags change**

  ```json
  {
  	...
  	"title": "Model version <model-version>/<version-counter> tags have changed",
  	"type": "model_version_tags_change",
  	"body": "Model version <model-version>/<version-counter> tags have changed.\n\n    New tags: <tags-separated-by-,>\n\n    Previous tags: <previous-tags-separated-by-,>",
  	...
  	"data": {
  		...
  		"model_version": {
  			...
  			"tags": [<tags-after-the-update>],
  			"previous_tags": [<previous-tags>]
  		},
  		...
  }
  ```
* **Model tags change**

  ```json
  {
  	...
  	"title": "Model <model-name> tags have changed",
  	"type": "model_tags_change",
  	"body": "Model <model-name> tags have changed.\n\n    New tags: <tags-separated-by-,>\n\n    Previous tags: <previous-tags-separated-by-,>",
  	...
  	"data": {
  		...
  		"model_version": {
  			## No other fields will be included apart from the two below
  			"tags": {
  				"current": [<tags-after-update>],
  				"previous": [<previous-tags>]
  			}
  		}
  	## dataset_version object will not be included for this event type
  	}
  }
  ```

## [Execution events](/automation-overview/triggers/notification-triggers.md#execution-events)

```json
{
  "project": <project-id>,
  "title": <notification-title>,
  "type": <notification-type>,
  "body": <notification-body>,
	"url": "/p/<project-owner-name>/<project-name>/execution/<execution-id>/",
	"data": {
		"valohai.execution-counter": <execution-counter>,
		"valohai.execution-ctime": <timestamp-when-execution-is-created>,
		"valohai.execution-duration": <duration-in-seconds>,
		"valohai.execution-id": <execution-id>,
		"valohai.execution-image": <execution-image>,
		"valohai.execution-qtime": <timestamp-when-execution-is-queued>,
		"valohai.execution-status": <"created" | "started" | "completed" | "error" | "stopped">,
		"valohai.execution-step": <step-name>,
		"valohai.execution-tags": [<executions-tags>],
		"valohai.execution-title": <execution-title | null>,
		"valohai.project-id": <project-id>,
		"valohai.project-name": <project-owner>/<project-name>,
		"valohai.environment-id": <environment-id>,
		"valohai.environment-name": <environment-name>,
		"valohai.environment-slug": <environment-slug>,
		"valohai.creator-id": <creator-id>,
		"valohai.creator-name": <username>,
		"valohai.creator-email": <creator-email | null>,
		"valohai.commit-identifier": <commit-id>
	}
}
```

> :bulb:Timestamps will be in the next format: `2025-12-16T15:36:52.445564+00:00`

> :exclamation:Dots (**`.`**) in the field names, under the `data` object, have to be escaped using **`\`** when used as a lookup path in the [notification trigger payload](/automation-overview/triggers/notification-triggers.md#payload-filtering).\
> For instance, if you want to run a trigger only when the step name of the completed execution is "training," the lookup path would be **`data.valohai\.execution-step`**.

Variations based on the notification type:

* **Execution is created**

  ```json
  {
      ...
  		"title": "Execution <project-owner>/<project-name>/#<execution-counter> created",
  		"type": "execution_created",
  		"body": "Execution [<project-owner>/<project-name>/#<execution-counter>](http://<installation-address>/p/<project-owner>/<project-name>/execution/<execution-id>/) was created by <username>.",
      ...
  }
  ```
* **Execution completes**

  ```json
  {
      ...
      "title": "Execution finished: <project-owner>/<project-name>/#<execution-counter> (completed)",
      "type": "execution_completed",
      "body": "Execution [<project-owner>/<project-name>/#<execution-counter>](http://<installation-address>/p/<project-owner>/<project-name>/execution/<execution-id>/) (by <username>) finished with duration <execution-duration>.",
      ...
  }
  ```
* **Execution is stopped**

  ```json
  {
      ...
      "title": "Execution finished: <project-owner>/<project-name>/#<execution-counter> (stopped)",
      "type": "execution_stopped",
      "body": "Execution [<project-owner>/<project-name>/#<execution-counter>](http://<installation-address>/p/<project-owner>/<project-name>/execution/<execution-id>/) (by <username>) finished with duration <execution-duration>.",
      ...
  }
  ```
* **Execution fails**

  ```json
  {
      ...
      "title": "Execution finished: <project-owner>/<project-name>/#<execution-counter> (error)",
      "type": "execution_errored",
      "body": "Execution [<project-owner>/<project-name>/#<execution-counter>](http://<installation-address>/p/<project-owner>/<project-name>/execution/<execution-id>/) (by <username>) finished with duration <execution-duration>.",
      ...
  }
  ```
* **Watchdog detects a failed execution**

  ```json
  {
      ...
      "title": "Execution failure detected by watchdog: <project-owner>/<project-name>/#<execution-counter> (error)",
      "type": "execution_errored_from_watchdog",
      "body": "Execution [<project-owner>/<project-name>/#<execution-counter>](http://<installation-address>/p/<project-owner>/<project-name>/execution/<execution-id>/) (by <username>) was marked as failed by watchdog with duration <execution-duration>.",
      ...
  }
  ```

> :bulb:`<installation-address>` in case you are using private/self-hosted installation, will be the address/domain name of your installation.
>
> Otherwise, it will be `app.valohai.com`

If the original execution that caused this trigger to run was part of a [Pipeline](/pipelines.md), the following fields will also be included in the `data` object:

```json
"data": {
    ...
    "valohai.pipeline-counter": <pipeline-counter>,
    "valohai.pipeline-id": <pipeline-id>,
    "valohai.pipeline-node-id": <pipeline-node-id>,
    "valohai.pipeline-title": <pipeline-title>,
    "valohai.pipeline-tags": [<pipeline-tags>],
    ...
}
```

If the original execution that caused this trigger to run was part of a [Task](/tasks.md), the following fields will also be included in the `data` object:

```json
"data": {
    ...
    "valohai.task-counter": <task-counter>,
    "valohai.task-id": <task-id>,
    ...
}
```

If the original execution that caused this trigger to run was also created/started by a trigger, the following fields will also be included in the `data` object:

```json
"data": {
    ...
    "valohai.trigger-id": <trigger-id>,
    "valohai.trigger-title": <trigger-title>
    ...
}
```

## [Pipeline events](/automation-overview/triggers/notification-triggers.md#pipeline-events)

```json
{
    "project": <project-id>,
    "title": <pipeline-title>,
    "type": <"pipeline_completed" | "pipeline_errored" | "pipeline_completed" | "pipeline_node_approval_required" | "pipeline_stopped">,
    "body": <notification-body>,
    "url": "/p/<project-owner>/<project-name>/pipeline/<pipeline-id>/",
    "data": {
        "valohai.pipeline-counter": <pipeline-counter>,
        "valohai.pipeline-id": <pipeline-id>,
        "valohai.pipeline-title": <pipeline-title>,
        "valohai.pipeline-tags": [pipeline-tags>],
        "valohai.project-id": <project-id>,
        "valohai.project-name": <project-owner>/<project-name>,
        "valohai.pipeline-n_complete_nodes": <number-of-completed-nodes>,
        "valohai.pipeline-n_error_nodes": <number-of-errored-nodes>,
        "valohai.pipeline-n_total_nodes": <total-number-of-nodes>
    }
}
```

> :exclamation: Dots (**`.`**) in the field names, under the `data` object, have to be escaped using **`\`** when used as a lookup path in the [notification trigger payload](/automation-overview/triggers/notification-triggers.md#payload-filtering).\
> For instance, if you want to run a trigger only when the title of the completed pipeline contains "training" in it, the lookup path would be **`data.valohai\.pipeline-title`**.

Variations based on the notification type:

* **Pipeline completes**

  ```json
  {
      ...
      "title": "Pipeline finished: <pipeline-owner>/<project-name>/=<pipeline-counter> (<pipeline-name>) (completed)",
      "type": "pipeline_completed",
      "body": "Pipeline [<pipeline-owner>/<project-name>/=<pipeline-counter> (<pipeline-name>)](http://<installation-address>/p/<project-owner>/<project>/pipeline/<pipeline-id>/) (by <username>) finished.\n\nOut of <total-number-of-nodes> nodes, <number-of-successful-nodes> were successful and <number-of-errored-nodes> failed.",
      ...
  }
  ```
* **Pipeline errors**

  ```json
  {
      ...
      "title": "Pipeline finished: <pipeline-owner>/<project-name>/=<pipeline-counter> (<pipeline-name>) (completed)",
      "type": "pipeline_errored",
      "body": "Pipeline [<pipeline-owner>/<project-name>/=<pipeline-counter> (<pipeline-name>)](http://<installation-address>/p/<project-owner>/<project>/pipeline/<pipeline-id>/) (by <username>) finished.\n\nOut of <total-number-of-nodes> nodes, <number-of-successful-nodes> were successful and <number-of-errored-nodes> failed.",
      ...
  }
  ```
* **Pipeline node approval required**

  ```json
  {
      ...
      "title": "Pipeline finished: <pipeline-owner>/<project-name>/=<pipeline-counter> (<pipeline-name>) (completed)",
      "type": "pipeline_node_approval_required",
      "body": "Node [<node-name> in <pipeline-owner>/<project-name>/=<pipeline-counter> (<pipeline-name>)](http://<installation-address>/p/<project-owner>/<project>/pipeline/<pipeline-id>/) (by <username>) requires human approval to be executed.",
      ...
  }
  ```

> :bulb:For the notification type of `Pipeline node approval required`, next fields will **not be** included under the `data` object:
>
> * `valohai.pipeline-n_complete_nodes`
> * `valohai.pipeline-n_error_nodes`
> * `valohai.pipeline-n_total_nodes`

* **Pipeline stops**

  ```json
  {
      ...
      "title": "Pipeline finished: <pipeline-owner>/<project-name>/=<pipeline-counter> (<pipeline-name>) (stopped)",
      "type": "pipeline_stopped",
      "body": "Pipeline [<pipeline-owner>/<project-name>/=<pipeline-counter> (<pipeline-name>)](http://<installation-address>/p/<project-owner>/<project>/pipeline/<pipeline-id>/) (by <username>) finished.\n\nOut of <total-number-of-nodes> nodes, <number-of-successful-nodes> were successful and <number-of-errored-nodes> failed.",
      ...
  }
  ```

## [Task events](/automation-overview/triggers/notification-triggers.md#task-events)

```json
{
    "project": <project-id>,
    "title": <pipeline-title>,
    "type": <"task_completed" | "task_errored" | "task_stopped">,
    "body": <notification-body>,
    "url": "/p/<project-owner>/<project-name>/task/<task-id>/",
    "data": {
        "valohai.project-id": <project-id>,
        "valohai.project-name": <project-owner>/<project-name>,
        "valohai.task-counter": <task-counter>,
        "valohai.task-id": <task-id>,
        "valohai.task-n_complete_executions": <number-of-completed-executions>,
        "valohai.task-n_error_executions": <number-of-errored-executions>,
        "valohai.task-n_total_executions": <total-number-of-executions>,
        "valohai.task-pipeline-n_complete_pipelines": <number-of-completed-pipelines>,
        "valohai.task-pipeline-n_error_pipelines": <number-of-errored-pipelines>,
        "valohai.task-pipeline-n_total_pipelines": <total-number-of-pipelines>
    }
}
```

> :bulb:[Tasks ](/tasks.md)allow you to run multiple pipelines in parallel as well (not only executions), based on the variation of one of the [pipeline parameters](/pipelines/pipeline-parameters.md).

> :exclamation: Dots (**`.`**) in the field names, under the `data` object, have to be escaped using **`\`** when used as a lookup path in the [notification trigger payload](/automation-overview/triggers/notification-triggers.md#payload-filtering).

Variations based on the notification type:

* **Task completes**

  ```json
  {
      ...
      "title": "Task finished: <project-owner>/<project>/!<task-counter> (complete)",
      "type": "task_completed",
      "body": "Task [<project-owner>/<project>/!<task-counter>](http://<installation-address>/p/<project-owner>/<project-name>/task/<task-id>/) (by <username>) finished.",
      ...
  }
  ```
* **Task fails**

  ```json
  {
      ...
      "title": "Task finished: <project-owner>/<project>/!<task-counter> (error)",
      "type": "task_errored",
      "body": "Task [<project-owner>/<project>/!<task-counter>](http://<installation-address>/p/<project-owner>/<project-name>/task/<task-id>/) (by <username>) finished.\n\nOut of <total-number-of-executions> executions, <number-of-completed-executions> were successful and <number-of-failed-executions> failed.",",
      ...
  }
  ```
* **Task stops**

  ```json
  {
      ...
      "title": "Task finished: <project-owner>/<project>/!<task-counter> (stopped)",
      "type": "task_stopped",
      "body": "Task [<project-owner>/<project>/!<task-counter>](http://<installation-address>/p/<project-owner>/<project-name>/task/<task-id>/) (by <username>) finished.\n\nOut of <total-number-of-executions> executions, <number-of-completed-executions> were successful and <number-of-failed-executions> failed.",",
      ...
  }
  ```

## [Deployment events](/automation-overview/triggers/notification-triggers.md#deployment-events)

* **Deployment finishes**

  <pre class="language-json"><code class="lang-json">{
      "project": &#x3C;project-id>,
      "type": "deployment_finished",
      "title": "Deployment &#x3C;deployment-version-name> ready",
      "body": <a data-footnote-ref href="#user-content-fn-1">HTML-BODY</a>,
      "url": &#x3C;deployment-version-url>,
      "data": {
          "valohai.deployment-version-id": &#x3C;deployment-version-id>,
          "valohai.deployment-id": &#x3C;deployment-id>,
          "valohai.project-id": &#x3C;project-id>,
          "valohai.project-name": &#x3C;project-owner>/&#x3C;project-name>,
      },
  }
  </code></pre>

  * **HTML-BODY format**

  ```html
  <h2>Deployment version created</h2>
  All enabled endpoints are ready in deployment {deployment-name} version {deployment-version}.
  <h3>Endpoint statuses</h3>
  <table>
  	<tr>
  		<td>Endpoint name</td>
  		<td>Enabled</td>
  	</tr>
  	<tr>
  		<td>{endpoint-name}</td>
  		<td>{True | False}</td>
  	</tr>
  	.
  	// repeating for each endpoint
  	.
  	.

  </table>

  ```

> :exclamation: Dots (**`.`**) in the field names, under the `data` object, have to be escaped using **`\`** when used as a lookup path in the [notification trigger payload](/automation-overview/triggers/notification-triggers.md#payload-filtering).

## [Resource Utilization events](/automation-overview/triggers/notification-triggers.md#resource-utilization-events)

```json
{
    "project": <project-id>,
    "title": "Underutilization: <project-owner>/<project-name>/#<execution-counter>",
    "type": "execution_with_underutilized_gpu_processor",
    "body": "Execution [MyOrg/linked_project/#274](http://<installation-address>/p/<project-owner>/<project-name>/execution/<execution-id>/#alerts) (by admin) reports resource underutilization:\n- The worker CPU was underutilized with 0% peak use.\n- The worker memory was underutilized with 0% peak use.",
    "url": "http://<installation-address>/p/<project-owner>/<project-name>/execution/<execution-id>/#alerts",
    "data": {}
}
```

> :bulb: Rely on the content of the `body` field for the correct (under)utilization values and the reason why this event is triggered, rather than on the `type` field.

## [User related events](/automation-overview/triggers/notification-triggers.md#user-related-events)

* **Mentioned in a comment**

  ```json
  {
      "project": <project-id>,
      "type": "comment_mention",
      "title": "Mentioned by @<who-mentioned> in <where-was-the-mention>",
      "body": "You were mentioned in a comment on <where-was-the-mention>(<url-to-the-page>)",
      "url": <url-to-the-page>
  }
  ```

[^1]: Checkout the section bellow for expected format


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.valohai.com/automation-overview/triggers/notification-triggers/notification-payload-formats.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.