---
title: "Execute ad-hoc agent"
method: POST
path: "/agent/v2/execute"
tags: ["Agents"]
---

# Execute ad-hoc agent

`POST /agent/v2/execute`

Creates an ephemeral agent and executes it immediately. By default this uses the lightweight synchronous linc runtime on Vercel Sandbox. Set `agentRuntime: true` to opt into the legacy Daytona-backed agent runtime.

## Request body

- object
  - `prompt` string, required
  - `instructions` string
  - `model` string
  - `agentRuntime` boolean, nullable — Set to true to opt into the legacy Daytona-backed agent runtime.
  - `vaultIds` string[], nullable
  - `objectIds` string[], nullable
  - `guidance` string, nullable
  - `enabledTools` string[], nullable
  - `disabledTools` string[], nullable
  - `sandbox` object, nullable
    - `cpu` integer
    - `memoryMiB` integer

## Response `200`

Run completed or started

- object
  - `runId` string
  - `agentId` string
  - `status` 'running' | 'completed' | 'failed'
  - `provider` 'daytona' | 'vercel'
  - `runtimeId` string, nullable
  - `runtimeState` 'running' | 'ended' | 'error'
  - `output` string, nullable
  - `error` string, nullable
  - `logs` object, nullable
    - `runner` string, nullable
    - `linc` string, nullable
  - `usage` object, nullable
  - `message` string, nullable

## Other responses

- `400` — Missing required fields (prompt)
- `401` — Invalid API key
- `403` — No agent access

## Changes

- **2026-03-31** `fb47823aff67` — 1 breaking, 5 warning, 6 info
  - the response property `message` became nullable for the status `200`
  - added the new `completed` enum value to the `status` response property for the response status `200`
  - added the new `ended` enum value to the `runtimeState` response property for the response status `200`
  - added the new `error` enum value to the `runtimeState` response property for the response status `200`
  - …8 more
- **2026-03-27** `220d723a75ba` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/casemark/apis/case-dev-api/changes/agent/v2/execute/post.md)

---

[API](https://skmtc.dev/casemark/apis/case-dev-api.md) · [All operations](https://skmtc.dev/casemark/apis/case-dev-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/casemark/case-dev-api/revisions/19bd0be9c80b/schema)