---
title: "Execute graph agent"
method: POST
path: "/api/graphs/{graph_id}/execute/{graph_version}"
tags: ["v1", "graphs"]
---

# Execute graph agent

`POST /api/graphs/{graph_id}/execute/{graph_version}`

## Path parameters

- `graph_id` string, required
- `graph_version` integer, nullable, required

## Query parameters

- `preset_id` string, nullable

## Request body

- BodyPostV1ExecuteGraphAgent
  - `inputs` object
  - `credentials_inputs` object
  - `source` 'builder' | 'library' | 'onboarding', nullable
  - `dry_run` boolean

## Response `200`

Successful Response

- GraphExecutionMeta
  - `id` string, required
  - `user_id` string, required
  - `graph_id` string, required
  - `graph_version` integer, required
  - `inputs` object, nullable, required
  - `credential_inputs` object, nullable, required
  - `nodes_input_masks` object, nullable, required
  - `preset_id` string, nullable, required
  - `status` 'INCOMPLETE' | 'QUEUED' | 'RUNNING' | 'COMPLETED' | 'TERMINATED' | 'FAILED' | 'REVIEW', required
  - `started_at` string, date-time, nullable — When execution started running. Null if not yet started (QUEUED).
  - `ended_at` string, date-time, nullable — When execution finished. Null if not yet completed (QUEUED, RUNNING, INCOMPLETE, REVIEW).
  - `is_shared` boolean
  - `share_token` string, nullable
  - `is_dry_run` boolean
  - `stats` Stats, required
    - `cost` integer — Execution cost (cents)
    - `duration` number — Seconds from start to end of run
    - `duration_cpu_only` number — CPU sec of duration
    - `node_exec_time` number — Seconds of total node runtime
    - `node_exec_time_cpu_only` number — CPU sec of node_exec_time
    - `node_exec_count` integer — Number of node executions
    - `node_error_count` integer — Number of node errors
    - `error` string, nullable — Error message if any
    - `activity_status` string, nullable — AI-generated summary of what the agent did
    - `correctness_score` number, nullable — AI-generated score (0.0-1.0) indicating how well the execution achieved its intended purpose

## Other responses

- `401` — Authentication required
- `402` — Payment required: NO_TIER paywall, or insufficient credit balance
- `422` — Validation Error
- `503` — Subscription state temporarily unavailable

## Changes

- **2026-05-08** `9b85f454ac38` — 2 info
  - added the non-success response with the status `402`
  - added the non-success response with the status `503`
- **2026-04-30** `8c84efcb3afb` — 2 warning, 2 info
  - removed the optional property `organization_id` from the response with the `200` status
  - removed the optional property `team_id` from the response with the `200` status
  - removed the non-success response with the status `402`
  - removed the non-success response with the status `503`

[Change history](https://skmtc.dev/significant-gravitas/apis/autogpt-agent-server/changes/api/graphs/:graph_id/execute/:graph_version/post.md)

---

[API](https://skmtc.dev/significant-gravitas/apis/autogpt-agent-server.md) · [All operations](https://skmtc.dev/significant-gravitas/apis/autogpt-agent-server/llms.txt) · [OpenAPI document](https://skmtc.dev/significant-gravitas/apis/autogpt-agent-server/revisions/72eaad2d41b3?raw)