---
title: "Automations API"
description: "Manage durable Agent Y2 Automation definitions and run history through the Y2 API."
canonical: https://y2.dev/docs/api/automations/
---

# Automations API

Manage durable Agent Y2 Automation definitions and run history through the Y2 API.

Automations run bounded Agent Y2 instructions on a schedule or after a selected profile report. Definitions and runs remain owner-private inside the API key workspace.

## Scopes and availability

| Operation                                          | Scope               |
| -------------------------------------------------- | ------------------- |
| List definitions, inspect one, or read run history | `automations:read`  |
| Create, update, archive, or request a manual run   | `automations:write` |

Automations and both API scopes require Pro or Elite. API requests use the app's workspace limits, permissions, overlap rules, and Agent Y2 credits.

## Create a scheduled Automation

Replace `projectId` with an accessible Project ID, or omit it for an Automation without a Project.

```
curl -sS "https://api.y2.dev/api/v1/automations" \
  -H "Authorization: Bearer $Y2_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: automation-daily-watch-2026-07" \
  -d '{
    "name": "Daily supply chain watch",
    "instructions": "Summarize material changes and cite the strongest evidence.",
    "projectId": "prj_0123456789abcdef01234567",
    "trigger": {
      "kind": "schedule",
      "frequency": "daily",
      "timeOfDay": "13:00",
      "timezone": "America/Chicago"
    },
    "notificationPolicy": "failures_only",
    "status": "active"
  }'
```

For a report-completion trigger, use:

```
{
  "kind": "profile_report_completed",
  "profileId": "prf_0123456789abcdef01234567"
}
```

## Inspect and update

Use `GET /api/v1/automations`, `GET /api/v1/automations/{automationId}`, and `GET /api/v1/automations/{automationId}/runs`. List responses are bounded to 50 rows per request. Definition and run-history collections return the standard opaque `nextCursor` and `links.next` fields for complete traversal.

`PATCH /api/v1/automations/{automationId}` accepts definition fields or a status-only lifecycle change. An archived Automation cannot be edited or resumed. Send the latest `ETag` in `If-Match` when coordinating multiple writers.

## Request a manual run

```
curl -sS -X POST "https://api.y2.dev/api/v1/automations/$AUTOMATION_ID/runs" \
  -H "Authorization: Bearer $Y2_API_KEY" \
  -H "Idempotency-Key: manual-run-2026-07-24T1500Z"
```

The endpoint returns `202 Accepted`. The idempotency key is required and prevents duplicate admission for retries. Poll the run-history endpoint for queued, running, terminal, usage, and billing state.

[Generated Automations reference](https://y2.dev/docs/api/reference/automations): Exact paths, parameters, request bodies, responses, and schemas

[Automations product guide](https://y2.dev/docs/automations): Triggers, plan limits, run states, billing, and live admission checks