Agent Execution

Start a durable agent execution

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.

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

Headers

Idempotency-Keystring

Opt-in idempotency token (max 255 chars). The FIRST request carrying a given key is processed normally and its 2xx response is cached for 24h, scoped to (api_key + method + path + request-body hash). A retry with the SAME key and body replays the cached response and adds Idempotency-Replayed: true. Reusing the same key with a DIFFERENT body returns 422 (idempotency_key_reuse). The cache is per-process and in-memory, so on a multi-replica deploy a retry that lands on a different task re-executes — callers must already tolerate at-least-once delivery.

Request body

messagestring required
session_idstring uuid
mode'auto' | 'deep'
domain'crypto' | 'us_equities' | 'india_stocks'
portfolio_idstring uuid nullable
include_portfolioboolean nullable
include_factstrue

Async agent executions always include the neutral evidence projection.

Response

Execution accepted

successtrue

Changes

No recorded changes to this operation across all 1 revision of this API.