---
title: "Run an automation"
method: POST
path: "/agents/repos/{owner}/{repo}/automations/{automation_id}/tasks"
tags: ["agent-automations"]
---

# Run an automation

`POST /agents/repos/{owner}/{repo}/automations/{automation_id}/tasks`

## Request

- Base URL: `https://api.github.com`
- URL: `https://api.github.com/agents/repos/{owner}/{repo}/automations/{automation_id}/tasks`
- Auth: none declared

> [!NOTE]
> This endpoint is in public preview and is subject to change.

Runs an automation in a repository. Set `event` to `manual` and optionally include
`context` of up to 10,000 characters, which will be injected into the automation's
prompt.

The repository must have the "Allow automations" setting enabled, and the automation
must be a personal automation belonging to you or a shared automation.

GitHub App installation access tokens can run shared automations.
The installation must belong to the repository owner and the token must have
"Agent tasks" repository permissions (write). Personal automations require a user token.

A successful response accepts the run request and includes a preallocated
`task_id`, which can be fetched with the "Get a task by repo" Agent tasks API.
It does not confirm execution or task creation. Task creation is asynchronous,
so fetching the task immediately may return `404 Not Found`, and downstream
skips or failures can prevent its creation.

To call this endpoint, you must have write access to the repository.

OAuth app tokens and personal access tokens (classic) need:

* the `repo` scope for private or internal repositories
* the `repo` scope or `public_repo` scope for public repositories

**Fine-grained access tokens for "Run an automation"**

This endpoint works with the following fine-grained token types:

* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)
* [GitHub App installation access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app)
* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)

The fine-grained token must have the following permission set:

* "Agent tasks" repository permissions (write)

## Path parameters

- `owner` string, required
- `repo` string, required
- `automation_id` string, required

## Request body

- object: Request body for requesting an automation run.
  - `event` 'manual', required: The event to trigger. Only `manual` is supported.
  - `context` string: Additional context for this automation run, up to 10,000 characters. Supported only when `event` is `manual`. The context supplements the automation's configured instructions.

## Response `202`

Automation run request accepted for asynchronous processing

- object: Response from accepting an automation run request.
  - `task_id` string, required: The preallocated ID of the accepted run. The task may not yet be readable, and downstream skips or failures can prevent its creation.
  - `automation_id` string, required: The ID of the automation that was triggered.
  - `event` 'manual', required: The trigger event name, always "manual" for public API runs.

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Insufficient permissions
- `404`: Resource not found
- `409`: Automation usage limit reached for the current period
- `422`: Validation failed
- `503`: Service unavailable

## Changes

- **2026-10-27** (2026-03-10) `18226de6c75a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/github/apis/rest/changes/agents/repos/:owner/:repo/automations/:automation_id/tasks/post.md)

---

[API](https://skmtc.dev/github/apis/rest.md) - [All operations](https://skmtc.dev/github/apis/rest/llms.txt) - [OpenAPI document](https://skmtc.dev/github/apis/rest/revisions/981aa3c25d9e?raw)