> 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.1**.
{% 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]` |
### Kognitos file
A file produced by a Kognitos run.
| Field Name | Description | Type |
| ------------------- | ------------------------------------------------ | ---------------- |
| [`content`](#thing) | The file's bytes. | `thing` |
| `file_name` | The file's name, when the platform recorded one. | `optional[text]` |
### Thing
No description
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## 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, and the optional `goal` query parameter:
```
GET https://docs.kognitos.com/guides/platform/integrations/kognitos.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.