---
title: "Start a durable agent execution"
method: POST
path: "/v1/agent/execute-async"
tags: ["Agent Execution"]
---

# Start a durable agent execution

`POST /v1/agent/execute-async`

## Request

- Base URL: `https://api.marketintell.ai`
- URL: `https://api.marketintell.ai/v1/agent/execute-async`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Queue a persisted Mastra workflow and return immediately. The run is owner-scoped, includes evidence by default, survives API process restarts when storage is configured, and can be polled or canceled. Use an Idempotency-Key to retry safely.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `message` string, required
  - `session_id` string, uuid
  - `mode` 'auto' | 'deep'
  - `domain` 'crypto' | 'us_equities' | 'india_stocks'
  - `portfolio_id` string, uuid, nullable
  - `include_portfolio` boolean, nullable
  - `include_facts` true: Async agent executions always include the neutral evidence projection.
  - `response_format` object
    - `type` 'text' | 'json_schema' | 'trade_setup'
    - `json_schema` object

## Response `202`

Execution accepted

- object
  - `success` true
  - `data` object
    - `contract_version` '1.0', required
    - `run_id` string, uuid, required
    - `status` 'pending', required
    - `poll_url` string, required
    - `retry_after_ms` integer, required

## Other responses

- `400`: Invalid input
- `401`: Authentication required
- `403`: Scope or tier denied
- `429`: Quota exhausted

---

[API](https://skmtc.dev/marketintell/apis/marketintell-api.md) · [All operations](https://skmtc.dev/marketintell/apis/marketintell-api/llms.txt) · [OpenAPI document](https://skmtc.dev/marketintell/apis/marketintell-api/revisions/f3ef87afc41f?raw)