# Get AI automation by ID

> GET /v1/ai/automations/{automationId} · AI and automations API

Source: https://developer.kustomer.com/api/ai/get-ai-automation-by-id

```http
GET https://{orgname}.api.kustomerapp.com/v1/ai/automations/{automationId}
Authorization: Bearer <API key>
```

## Authorization

Requires any one of these roles: `org.permission.assistant.read`; or legacy `org.user.apps.read`. The API key or user must hold at least one of them. Legacy roles predate permission sets and still work.

Retrieves a specific AI automation by its unique ID.

## About AI automations

An AI automation is an AI agent built in Kustomer, such as one that answers customers in chat or one that helps your team with their work. The API lists them so you can find an agent's ID, mainly to test it with evaluations; building and editing agents happens in Kustomer.

AI automations are the AI agents your org builds in Kustomer. Each one has instructions, tools it can call, and triggers: the events that start it. These endpoints are read-only: you can't create, edit, turn on or delete an agent through the API. Their main use is finding the `automationId` you need to create and run [evaluations](https://developer.kustomer.com/api/ai#evaluations), and listing your agents for an inventory or dashboard.

#### Key fields

| Field | Meaning |
| --- | --- |
| `name`, `description` | What the agent is called and what it's for. |
| `type` | The kind of agent: `customer` for agents that talk to your customers, `rep` for agents that help your team, and also `conversational` or `workflow`. |
| `machineUserId` | The Kustomer user the agent acts as. |
| `version` | The agent version. The API returns version `0`, the agent's current draft, which is also the version evaluations test. |
| `createdAt`, `updatedAt`, `modifiedAt` | When the agent was created and last changed. |

#### Filtering

`GET /v1/ai/automations` returns only one type at a time, and `type` defaults to `customer`, so ask for `type=rep` (or another type) explicitly to see other agents. `name` filters by name, and `triggers` takes a comma-separated list of trigger event names to find the agents that respond to them.

#### Which endpoint to use

| To | Call |
| --- | --- |
| List your AI agents of one type | [`GET /v1/ai/automations`](https://developer.kustomer.com/api/ai/list-ai-automations) |
| Look up one agent by ID | [`GET /v1/ai/automations/{automationId}`](https://developer.kustomer.com/api/ai/get-ai-automation-by-id) |
| List the evaluations that test an agent | [`GET /v1/ai/automations/{automationId}/evaluations`](https://developer.kustomer.com/api/ai/list-evaluations-for-an-automation) |

Results are paginated with `page` and `pageSize`. These endpoints need the AI Agents feature on your Kustomer plan; without it, they return `403 Forbidden`. Reading automations only needs read access to apps or AI agents, so a read-only API key is enough for listing and evaluation scripts.

Related: [AI and automations API](https://developer.kustomer.com/docs/ai/ai-api), [Evaluations](https://developer.kustomer.com/api/ai#evaluations), [Users](https://developer.kustomer.com/api/access-management#users)

### Recipes

#### 1. Find an AI agent's ID by name

Turn the agent name people use into the `automationId` that evaluation scripts and CI jobs need, then find the evaluations that already test it.

**Step 1.** [`GET /v1/ai/automations`](https://developer.kustomer.com/api/ai/list-ai-automations.md). List agents with `name` and the right `type`. `type` defaults to `customer`, so an agent that helps your team only comes back with `type=rep`. Compare `attributes.name` yourself to be sure you have an exact match, and keep the record's `id`: that's the `automationId`.

```bash title="cURL"
curl --get "https://api.kustomerapp.com/v1/ai/automations" \
  --data-urlencode "type=customer" \
  --data-urlencode "name=$AGENT_NAME" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
kusty api GET /v1/ai/automations --query type=customer --query "name=$AGENT_NAME" --all \
  | jq -r --arg name "$AGENT_NAME" 'select(.data.attributes.name == $name) | .data.id'
```

**Step 2.** [`GET /v1/ai/automations/{automationId}/evaluations`](https://developer.kustomer.com/api/ai/list-evaluations-for-an-automation.md). List the agent's evaluations to reuse one instead of creating a duplicate; names are unique per agent. A `404` means no agent has that ID.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/ai/automations/$AUTOMATION_ID/evaluations?pageSize=100" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
kusty api GET /v1/ai/automations/$AUTOMATION_ID/evaluations --all \
  | jq -r '[.data.id, .data.attributes.name] | @tsv'
```

> A `403` on these endpoints usually means your plan doesn't include AI Agents. A read-only API key is enough for both calls.

#### 2. Inventory every AI agent and its evaluations

Build a list of all your AI agents of every type, how many evaluations test each one, and which user each one acts as, for an audit or dashboard.

**Step 1.** [`GET /v1/ai/automations`](https://developer.kustomer.com/api/ai/list-ai-automations.md). The list returns one `type` per request, so ask for each of `customer`, `rep`, `conversational` and `workflow` in turn and page through each. Keep `id`, `name`, `type` and `machineUserId`.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/ai/automations?type=rep&pageSize=250" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
for t in customer rep conversational workflow; do
  kusty api GET /v1/ai/automations --query type=$t --all
done | jq -c '.data | {id, name: .attributes.name, type: .attributes.type, user: .attributes.machineUserId}' > agents.jsonl
```

**Step 2.** [`GET /v1/ai/automations/{automationId}/evaluations`](https://developer.kustomer.com/api/ai/list-evaluations-for-an-automation.md). Count each agent's evaluations. An agent with none has no automated tests guarding changes to it.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/ai/automations/$AUTOMATION_ID/evaluations?pageSize=100" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
jq -r .id agents.jsonl | while read -r id; do
  printf '%s\t%s\n' "$id" "$(kusty api GET /v1/ai/automations/$id/evaluations --all | wc -l)"
done
```

**Step 3.** [`GET /v1/users/{id}`](https://developer.kustomer.com/api/access-management/get-user-by-id.md). `machineUserId` is the Kustomer user the agent acts as. Look each one up for a readable name, so you can tell which agent is behind records attributed to that user.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/users/$MACHINE_USER_ID" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
kusty api GET /v1/users/$MACHINE_USER_ID --fields attributes.name,attributes.userType
```

### Example object

A real record from [`GET /v1/ai/automations/{automationId}`](https://developer.kustomer.com/api/ai/get-ai-automation-by-id.md):

```json
{
  "id": "507f1f77bcf86cd799439011",
  "type": "automation",
  "attributes": {
    "name": "Customer Support Agent",
    "machineUserId": "507f1f77bcf86cd799439099",
    "description": "Handles customer support inquiries",
    "version": 0,
    "type": "customer",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z",
    "modifiedAt": "2024-01-15T10:30:00.000Z"
  },
  "relationships": {
    "org": {
      "links": {
        "self": "/v1/orgs/507f1f77bcf86cd799439010"
      },
      "data": {
        "type": "org",
        "id": "507f1f77bcf86cd799439010"
      }
    },
    "user": {
      "links": {
        "self": "/v1/users/507f1f77bcf86cd799439099"
      },
      "data": {
        "type": "user",
        "id": "507f1f77bcf86cd799439099"
      }
    },
    "modifiedBy": {
      "links": {
        "self": "/v1/users/507f1f77bcf86cd799439099"
      },
      "data": {
        "type": "user",
        "id": "507f1f77bcf86cd799439099"
      }
    }
  },
  "links": {
    "self": "string"
  }
}
```

Fields:

- `id` (string): The `automationId` you send when creating an evaluation and in `GET /v1/ai/automations/{automationId}/evaluations`.
- `type` (string): Resource type
- `attributes` (object): Automation attributes
- `attributes.name` (string): The agent's name as shown in Kustomer. Filter the list on it with the `name` query parameter.
- `attributes.machineUserId` (string): The Kustomer user the agent acts as, a machine user rather than a person. The same ID as `relationships.user`.
- `attributes.description` (string): What the agent is for, written by whoever built it. Left out when nobody wrote one.
- `attributes.version` (integer): Always `0`: the API returns only the agent's current draft, which is also the version evaluations run against.
- `attributes.type` (string): `customer` agents talk to your customers and `rep` agents help your team; `conversational` and `workflow` are the other kinds. The list returns one type per request and defaults to `customer`.
- `attributes.createdAt` (string (date-time)): Creation timestamp
- `attributes.updatedAt` (string (date-time)): Last update timestamp
- `attributes.modifiedAt` (string (date-time)): Last modification timestamp
- `relationships.user` (object): The machine user the agent acts as, the same ID as `machineUserId`. Look it up with [`GET /v1/users/{id}`](https://developer.kustomer.com/api/access-management/get-user-by-id) to show its name.
- `links.self` (string): URL for this resource

### Relationships

- Points to **Users** via `relationships.user`: The machine user an AI automation acts as in Kustomer, the same ID as the automation's `machineUserId`.
- Referenced by **AI evaluations** via `relationships.automation`: The AI automation an evaluation tests, from the evaluation's `automationId`. An automation can have up to 30 evaluations, listed with `GET /v1/ai/automations/{automationId}/evaluations`.

### Permissions

Fewest roles for a read-only integration: `org.permission.assistant.read`. For every endpoint: `org.permission.assistant.read`.

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `automationId` | string | yes | Automation ID |

## Responses

### 200

OK

- `data` (object)
  - `id` (string): Unique automation identifier
  - `type` (string): Resource type
  - `attributes` (object): Automation attributes
    - `name` (string): Name of the automation
    - `machineUserId` (string): Machine user ID associated with the automation
    - `description` (string): Description of the automation
    - `version` (integer): Automation version
    - `type` (string): Automation type One of: `customer`, `rep`, `conversational`, `workflow`.
    - `createdAt` (string<date-time>): Creation timestamp
    - `updatedAt` (string<date-time>): Last update timestamp
    - `modifiedAt` (string<date-time>): Last modification timestamp
  - `relationships` (object)
    - `org` (object)
    - `user` (object)
    - `modifiedBy` (object)
  - `links` (object)
    - `self` (string): URL for this resource

```json
{
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "type": "automation",
    "attributes": {
      "name": "Customer Support Agent",
      "machineUserId": "507f1f77bcf86cd799439099",
      "description": "Handles customer support inquiries",
      "version": 0,
      "type": "customer",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z",
      "modifiedAt": "2024-01-15T10:30:00.000Z"
    },
    "relationships": {
      "org": {
        "links": {
          "self": "/v1/orgs/507f1f77bcf86cd799439010"
        },
        "data": {
          "type": "org",
          "id": "507f1f77bcf86cd799439010"
        }
      },
      "user": {
        "links": {
          "self": "/v1/users/507f1f77bcf86cd799439099"
        },
        "data": {
          "type": "user",
          "id": "507f1f77bcf86cd799439099"
        }
      },
      "modifiedBy": {
        "links": {
          "self": "/v1/users/507f1f77bcf86cd799439099"
        },
        "data": {
          "type": "user",
          "id": "507f1f77bcf86cd799439099"
        }
      }
    },
    "links": {
      "self": "string"
    }
  }
}
```

### 401

Unauthorized - Authentication required or invalid token

### 403

Forbidden - Insufficient permissions or AI Agents feature not enabled

### 404

Not Found - Resource does not exist

## Example request

```bash
curl --request GET \
  --url 'https://api.kustomerapp.com/v1/ai/automations/507f1f77bcf86cd799439011' \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```