> For the complete documentation index, see [llms.txt](https://docs.erathos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.erathos.com/api/concepts/metadata.md).

# Metadata

## Overview

To assist in creating custom logic and handling based on execution results, the platform provides a series of metadata related to job executions. Use it in a webhook in two ways:

* **In rules**, by the uppercase name in the table below (e.g. `"variable_name": "ROWS"`), to decide whether the webhook is sent. See [Rules](/api/concepts/rules.md).
* **In the url, header or body**, as `${{erathos.name}}` (e.g. `${{erathos.rows}}`), to send its value. Names are case-insensitive here, and values are inserted as text.

The metadata available in both rules and templates:

<table><thead><tr><th>Name</th><th width="124">Type</th><th>Description</th></tr></thead><tbody><tr><td>JOB_ID</td><td><code>uuid</code></td><td>Unique Job Identifier: Represents an endpoint for API connectors or a table for database connections. This unique identifier is used to distinguish and track specific jobs within the platform.</td></tr><tr><td>CONNECTION_ID</td><td><code>uuid</code></td><td>Unique identifier of the source connection the job belongs to.</td></tr><tr><td>CONNECTION_NAME</td><td><code>string</code></td><td>Connection Name</td></tr><tr><td>SCHEMA_NAME</td><td><code>string</code></td><td>Name of the schema used for the pipeline tables in the destination Data Warehouse.</td></tr><tr><td>TABLE_NAME</td><td><code>string</code></td><td>Name of the table or endpoint in the destination Data Warehouse.</td></tr><tr><td>EXECUTION_ID</td><td><code>uuid</code></td><td>Identifier of the job execution that triggered the webhook.</td></tr><tr><td>STATUS</td><td><code>string</code></td><td>Final status of the execution (FINISHED, FAILED).</td></tr><tr><td>ROWS</td><td><code>integer</code></td><td>Number of rows found during the execution.</td></tr><tr><td>COLUMNS</td><td><code>integer</code></td><td>Number of selected columns.</td></tr><tr><td>TOTAL_DURATION</td><td><code>integer</code></td><td>Execution duration in seconds.</td></tr><tr><td>TRIGGERED_BY</td><td><code>string</code></td><td><p>Indicates the origin of the execution, divided into:</p><ul><li>Erathos Schedule: regular schedules based on the selected frequency.</li><li>User's Email: manual executions via the platform.</li><li>API Key Owner's Email: programmatic triggers via the API.</li></ul></td></tr><tr><td>IS_ORCHESTRATION</td><td><code>boolean</code></td><td>Indicator <strong>True</strong> for executions triggered programmatically or <strong>False</strong> for executions triggered by scheduling or manually via the platform.</td></tr><tr><td>FORCE_HISTORY</td><td><code>boolean</code></td><td>Indicator <strong>True</strong> for <code>FULL</code> type executions and <strong>False</strong> for <code>PARTIAL</code> type executions.</td></tr><tr><td>NESTED_TABLE</td><td><code>boolean</code></td><td>Indicator if the table is nested (always False for database connectors).</td></tr><tr><td>FINISHED_AT_DATE</td><td><code>date</code></td><td>Completion date of the execution in YYYY-MM-DD format.</td></tr><tr><td>FINISHED_AT_TIME</td><td><code>time</code></td><td>Time of completion of the execution in UTC time zone and in HH:MM format.</td></tr><tr><td>FINISHED_AT_WEEKDAY</td><td><code>integer</code></td><td>Day of the week corresponding to the completion of the execution (0 - Sunday, 1 - Monday, 2 - Tuesday, 3 - Wednesday, 4 - Thursday, 5 - Friday, 6 - Saturday).</td></tr></tbody></table>

### Template-only metadata

These can be used in the url, header or body (`${{erathos.name}}`), but not in rules:

| Name                                         | Type      | Description                                                                                                                                                                                                                                                                              |
| -------------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `connector_id`                               | `uuid`    | Identifier of the source connector type, the same for every connection of that type (e.g. every PostgreSQL connection). `connection_id` used to carry this value by mistake; webhooks that used it were switched to `connector_id` when that was fixed, so what they send didn't change. |
| `enable_delete`                              | `boolean` | Whether the run was started manually with deleting removed rows enabled.                                                                                                                                                                                                                 |
| `invalid_datatype_rows`                      | `integer` | Rows with a value that didn't match its column's data type.                                                                                                                                                                                                                              |
| `extract_requests` / `load_requests`         | `integer` | Requests made to the source / destination during the run.                                                                                                                                                                                                                                |
| `extract_retries` / `load_retries`           | `integer` | Requests to the source / destination that had to be retried.                                                                                                                                                                                                                             |
| `extract_backoff_time` / `load_backoff_time` | `float`   | Seconds spent waiting on the source / destination, e.g. because of rate limits.                                                                                                                                                                                                          |
| `execution_cursor`                           | list      | The incremental cursor values the run used, inserted as text.                                                                                                                                                                                                                            |

## Alternative usage

In addition to orchestrating external tasks, webhooks can also be used as a method for ingesting execution metadata, which can be sent to various destinations or even to a custom API.

```json

{
  "description": "Send metadata to custom API",
  "is_active": true,
  "method": "POST",
  "url": "https://${{variables.api_url}}",
  "header": {
    "Authorization": "${{secrets.token}}" 
  },
  "body": {
    "job_id": "${{erathos.job_id}}",
    "connection_id": "${{erathos.connection_id}}",
    "connector_id": "${{erathos.connector_id}}",
    "connection_name": "${{erathos.connection_name}}",
    "schema_name": "${{erathos.schema_name}}",
    "table_name": "${{erathos.table_name}}",
    "execution_id": "${{erathos.execution_id}}",
    "status": "${{erathos.status}}",
    "rows": "${{erathos.rows}}",
    "columns": "${{erathos.columns}}",
    "total_duration": "${{erathos.total_duration}}",
    "triggered_by": "${{erathos.triggered_by}}",
    "is_orchestration": "${{erathos.is_orchestration}}",
    "force_history": "${{erathos.force_history}}",
    "nested_table": "${{erathos.nested_table}}",
    "finished_at_date": "${{erathos.finished_at_date}}",
    "finished_at_time": "${{erathos.finished_at_time}}",
    "finished_at_weekday": "${{erathos.finished_at_weekday}}"
  },
  "rules": [
  ],
  "jobs": [
    "<ERATHOS_JOB1_ID>",
    "<ERATHOS_JOB2_ID>",
    ...
    "<ERATHOS_JOBN_ID>"
  ]
}
```