> For the complete documentation index, see [llms.txt](https://docs.kognitos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kognitos.com/guides/platform/integrations/kognitos.md).
# Kognitos Automations
Overview of the Kognitos Automations integration.
{% hint style="info" %}
The following documentation is for **Kognitos Automations v2.6.3**.
{% endhint %}
## Overview
Kognitos Automations lets one automation run another and track how it went. Use it to split work between a parent automation that fans out and a child automation that handles a single item. Each invocation creates its own run, so one item failing leaves the others untouched and every item ends with a status you can report on or retry.
## Setup
The following integrations need to be connected to your Kognitos workspace:
* **Kognitos Automations**
### Steps
Follow these steps to connect the integration in Kognitos:
{% stepper %}
{% step %}
#### Navigate
Using the left navigation menu, go to **Integrations** → **Explore Integrations**.
{% endstep %}
{% step %}
#### Find
Search for the integration and click on it.
{% endstep %}
{% step %}
#### Connect
Click on **Connect** to add a connection to the integration.
{% endstep %}
{% step %}
#### Configure
Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**.
{% endstep %}
{% endstepper %}
### Credentials
This integration connects to a Kognitos workspace, which can be the workspace the automation already runs in or a different one. You need three values.
#### 1. API Key
{% stepper %}
{% step %}
**Open API Keys**
Click on your name or profile avatar in the bottom-left corner to open the user menu, then select **API Keys**.
{% endstep %}
{% step %}
**Create a Key**
Click **Create API Key**, then scope the key to the workspace whose automations you want to invoke. See [**API Keys**](/guides/api-reference/api-keys.md) for the full set of options.
{% endstep %}
{% step %}
**Copy the Key**
Copy the key as soon as it is created. It is shown only once.
{% endstep %}
{% endstepper %}
{% hint style="info" %}
The key needs permission to list and invoke automations and to read runs in the target workspace. A key limited to read-only access can list automations and runs but cannot invoke them.
{% endhint %}
#### 2. Organization Id and Workspace Id
Open the target workspace in Kognitos and read both values from the address bar. A workspace URL has the form `/o//w/`.
## Authentication
Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements.
### Connect using API Key, Organization Id and Workspace Id
Connect to a Kognitos workspace using an API key.
| Label | Description | Type |
| --------------- | --------------------------------------------------- | ----------- |
| API Key | An API key generated in the Kognitos UI. | `sensitive` |
| Organization Id | The organization that owns the workspace. | `text` |
| Workspace Id | The workspace whose automations you want to invoke. | `text` |
### Configuration
The following options control how this integration reaches Kognitos. Both have defaults and only need changing in specific cases.
| Option | Description | Type | Default |
| ---------- | --------------------------------------------------------------------- | -------- | ------------------------------- |
| `base url` | Root URL of the Kognitos deployment to call, without a trailing path. | `text` | `https://app.us-1.kognitos.com` |
| `timeout` | Seconds to wait for any single call to the Kognitos API. | `number` | `30.0` |
Set either option in plain language:
```generic
the department's Kognitos Automations's base url is https://app.us-1.kognitos.com
```
{% hint style="info" %}
Change `base url` only when the target workspace lives in a different Kognitos deployment than the default. It must point at a Kognitos deployment, because the connection's API key is sent to that host as a bearer token.
{% endhint %}
## Actions
The following actions are available in the **Kognitos Automations** integration:
### 1. Await a kognitos run's completion
Wait until a run finishes, then report how it went.
### 2. Continue a kognitos run
Resume a run that was paused, from where it stopped.
### 3. Get a kognitos automation
Look up one automation by name or by id.
### 4. Get a kognitos connection
Check whether an integration will serve a call before relying on it.
### 5. Get a kognitos run
Look up a run you already know the id of.
### 6. Get a kognitos run's status
Check how a run is doing, without waiting for it.
### 7. Get the kognitos run statistics
Report how many runs each automation has, and how many completed.
### 8. Invoke a kognitos automation
Start another automation and return its run straight away.
### 9. Invoke a kognitos automation for each item
Run one automation once per item and report how each one went.
### 10. List a kognitos automation's runs
List recent runs of an automation, newest first.
### 11. List a kognitos run's events
List what happened during a run, step by step.
### 12. List the kognitos automations
List the automations this connection can invoke.
### 13. Pause a kognitos run
Pause a run that is currently executing.
### 14. Read a kognitos file
Fetch the contents of a file a run produced.
## Concepts
### Kognitos run
A single execution of a Kognitos automation.
| Field Name | Description | Type |
| --------------- | ------------------------------------------------------- | ------ |
| `run_id` | The run's unique identifier. | `text` |
| `automation_id` | The automation that was invoked. | `text` |
| `stage` | Whether the draft or the published version was invoked. | `text` |
### Kognitos run status
The observed state of a Kognitos run.
| Field Name | Description | Type |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| `run_id` | The run this status describes. | `text` |
| `automation_id` | The automation the run belongs to. | `text` |
| `state` | One of pending, executing, stopping, stopped, awaiting guidance, completed or failed. | `text` |
| `is_finished` | True when the run will not change state on its own. | `boolean` |
| `outputs` | The run's outputs. Only populated once it has completed. | `optional[json]` |
| `error_id` | The identifier of the error that failed the run. Worth recording alongside a failed item: it is what support needs to find the failure. | `optional[text]` |
| `error_description` | Why the run failed, when it failed. | `optional[text]` |
| `exception_id` | The Guidance Center exception blocking the run, when it is awaiting guidance. | `optional[text]` |
| `exception_description` | What that exception says. | `optional[text]` |
| `timed_out` | True when a wait gave up before the run finished. The run itself is unaffected and keeps going. | `optional[boolean]` |
### Kognitos automation
An automation in the connected Kognitos workspace.
| Field Name | Description | Type |
| -------------------------- | --------------------------------------------------- | ------------------------ |
| `automation_id` | The automation's unique identifier. | `text` |
| `display_name` | The automation's name as it appears in the product. | `text` |
| `description` | What the automation does, if its author wrote one. | `optional[text]` |
| `input_names` | Names of the inputs the automation accepts. | `optional[list of text]` |
| `latest_published_version` | The newest published version, if any. | `optional[text]` |
### Kognitos connection
A book connection in the workspace, and whether it will serve a call.
| Field Name | Description | Type |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
| `connection_id` | The connection's unique identifier. | `text` |
| `state` | One of ready, inactive, pending, failed, conditions not met or unknown. | `text` |
| `is_usable` | True when the connection will serve a call, either at once or after waking from idle. Check this rather than comparing the state, so an idle connection is not mistaken for a broken one. | `boolean` |
| `connection_name` | The connection's name as it appears in the product. | `optional[text]` |
| `book_name` | The integration this connection is for. | `optional[text]` |
| `book_version` | The version of that integration in use. | `optional[text]` |
| `reason` | Why the connection is in this state, when it says. | `optional[text]` |
### Kognitos run statistic
Run counts for one automation in the connected workspace.Only two counts are reported, because they are the only two the platform aggregates. `total_runs - completed_runs` is *not* a failure count: it also covers runs that are still executing, were stopped, or are awaiting guidance. Use `list a kognitos automation's runs` to tell those apart.
| Field Name | Description | Type |
| ---------------- | ------------------------------------------ | -------- |
| `automation_id` | The automation these counts describe. | `text` |
| `total_runs` | Every run ever created for the automation. | `number` |
| `completed_runs` | Runs that finished successfully. | `number` |
### Kognitos run event
One entry from a run's execution log.The platform returns two very different kinds of event on the same stream: a run-level state change, and a fine-grained step event from the execution engine. Both are flattened to this one shape so an automation can walk the log without branching on which kind it got. `details` carries the raw payload for the cases where the summary is not enough.
| Field Name | Description | Type |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
| `event_type` | What kind of event this is, as a lowercase phrase -- "run update" for a run-level state change, or the engine's own event name such as "node executed" or "failed". | `text` |
| `summary` | A one-line description, suitable for logging or an exception message. | `text` |
| `occurred_at` | When the event was recorded -- for a run-level update, the moment the run entered that state; for an engine event, when the engine recorded it. | `optional[text]` |
| `details` | The raw event payload, unflattened. | `optional[json]` |