--- title: "List workflows" method: GET path: "/workflows" tags: ["Workflows"] --- # List workflows `GET /workflows` ## Query parameters - `smartWalletAddress` EthereumAddress[] - `status` WorkflowStatus[] - `before` string - `after` string - `limit` integer ## Response `200` Page of workflows. - WorkflowList - `data` Workflow[], required - `id` string, required — ULID identifier (26-char Crockford base32). - `name` string - `owner` string, required — Lowercase or checksummed hex EOA / contract address. - `smartWalletAddress` string, required — Lowercase or checksummed hex EOA / contract address. - `trigger` union, required - object - `type` 'manual', required - `config` ManualTriggerConfig, required — User-initiated trigger; no chain context. - `data` unknown - `headers` object — HTTP headers (for webhook testing). - `pathParams` object — Path parameters (for webhook testing). - `lang` 'javascript' | 'json' | 'graphql' | 'handlebars', required — Language/format of an inline payload (e.g., custom code source, manual trigger data). Mirrors the proto `Lang` enum minus the `LANG_` prefix. Wire values are lowercase. - object - `type` 'fixedTime', required - `config` FixedTimeTriggerConfig, required — Fires at one or more absolute Unix-epoch milliseconds. - `epochs` integer[], required - object - `type` 'cron', required - `config` CronTriggerConfig, required — Fires on one or more cron schedules. - `schedules` string[], required - `timezone` string — IANA timezone (e.g., `UTC`, `America/New_York`). Default UTC. - object - `type` 'block', required - `config` BlockTriggerConfig, required — Fires every N blocks on the target chain. - `interval` integer, required — Fire every N blocks. - `chainId` integer, required — Numeric chain ID (e.g. 11155111 for Sepolia, 8453 for Base). On chain-aware trigger/node configs this is required and must be a configured chain; on query/filter params it is optional. - object - `type` 'event', required - `config` EventTriggerConfig, required — Fires when matching on-chain events are observed. - `queries` EventTriggerQuery[], required - `addresses` EthereumAddress[] — Contract addresses to filter events from. Empty matches any contract. - `topics` string[] — Topic filters (`topics[0]` is the event signature, `topics[1..]` are indexed parameter values). `null` means wildcard at that position. - `maxEventsPerBlock` integer — Safety ceiling per query per block. Exceeded → task cancelled. - `contractAbi` unknown[] — Contract ABI entries (JSON form) for event decoding. - … - `conditions` EventCondition[] — Filters applied to decoded event data. - … - `methodCalls` EventMethodCall[] — Method calls used to enrich decoded event data (e.g., `decimals`). - … - `cooldownSeconds` integer — Seconds to wait after a fire before allowing the same task to trigger again. Default 300. 0 disables cooldown. - `chainId` integer, required — Numeric chain ID (e.g. 11155111 for Sepolia, 8453 for Base). On chain-aware trigger/node configs this is required and must be a configured chain; on query/filter params it is optional. - `nodes` Node[], required - union - object - `type` 'ethTransfer', required - `config` ETHTransferNodeConfig, required - `destination` string, required — Lowercase or checksummed hex EOA / contract address. - `amount` string, required — Amount in wei (decimal string for big-int safety). Special value `max` withdraws the entire balance. - `chainId` integer, required — Numeric chain ID (e.g. 11155111 for Sepolia, 8453 for Base). On chain-aware trigger/node configs this is required and must be a configured chain; on query/filter params it is optional. - object - `type` 'contractWrite', required - `config` ContractWriteNodeConfig, required - `contractAddress` string, required — Lowercase or checksummed hex EOA / contract address. - `callData` string — Arbitrary-length hex-encoded byte string. - `contractAbi` unknown[] - … - `methodCalls` MethodCall[] - … - `isSimulated` boolean — When true, use Tenderly simulation instead of sending a real UserOp. - `value` string — ETH value to send with the call (wei, decimal string). - `gasLimit` string — Custom gas limit (decimal string). - `chainId` integer, required — Numeric chain ID (e.g. 11155111 for Sepolia, 8453 for Base). On chain-aware trigger/node configs this is required and must be a configured chain; on query/filter params it is optional. - object - `type` 'contractRead', required - `config` ContractReadNodeConfig, required - `contractAddress` string, required — Lowercase or checksummed hex EOA / contract address. - `contractAbi` unknown[] - … - `methodCalls` MethodCall[] - … - `chainId` integer, required — Numeric chain ID (e.g. 11155111 for Sepolia, 8453 for Base). On chain-aware trigger/node configs this is required and must be a configured chain; on query/filter params it is optional. - object - `type` 'graphqlQuery', required - `config` GraphQLQueryNodeConfig, required - `url` string, uri, required - `query` string, required - `variables` object - object - `type` 'restApi', required - `config` RestAPINodeConfig, required - `url` string, uri, required - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS', required - `headers` object - `body` string - `options` object — Generic options bag for backend features on terminal RestAPI nodes. `summarize: true` opts a SendGrid /v3/mail/send or Telegram /sendMessage node into the aggregator's context-memory summarizer, which composes a subject + HTML body from the workflow's execution context and injects them into the outgoing request. Without this field set, the aggregator falls back to the deterministic summarizer (no LLM polish). - … - object - `type` 'customCode', required - `config` CustomCodeNodeConfig, required - `lang` 'javascript' | 'json' | 'graphql' | 'handlebars', required — Language/format of an inline payload (e.g., custom code source, manual trigger data). Mirrors the proto `Lang` enum minus the `LANG_` prefix. Wire values are lowercase. - `source` string, required - object - `type` 'branch', required - `config` BranchNodeConfig, required - `conditions` BranchCondition[], required - … - object - `type` 'filter', required - `config` FilterNodeConfig, required - `inputVariable` string, required — Template path for the source array (e.g., `{{custom_code1.data}}`). - `expression` string, required — JavaScript predicate evaluated per item. - object - `type` 'loop', required - `config` LoopNodeConfig, required — Iterates over an input array, running an inner Node per item. The runner node is one of the chain-aware or chain-agnostic node types; a chain-aware runner must specify its own required `chainId` (there is no inheritance from the loop or workflow). - `inputVariable` string, required — Template path for the iterable (e.g., `{{settings.addressList}}`). - `iterVar` string — Name of the per-iteration variable (defaults to `value`). - `runner` Node, required — recursive - object - `type` 'balance', required - `config` BalanceNodeConfig, required - `address` string, required — Lowercase or checksummed hex EOA / contract address. - `chain` string, required — Chain name or numeric ID (e.g., `ethereum`, `base`, `1`, `8453`). - `includeSpam` boolean - `includeZeroBalances` boolean - `minUsdValueCents` integer — Filter out tokens with USD value below this many cents. - `tokenAddresses` EthereumAddress[] — Restrict to these tokens. Empty = fetch all. - object - `type` 'await', required - `config` AwaitNodeConfig, required — Pauses the workflow until a wake arrives (durable execution). Two mutually exclusive flavors: the external-signal flavor (human approval — set `channel`, e.g. a Telegram approve/reject), or the chain-event flavor (cross-chain — set `chainEvent` to pause until an operator observes that on-chain event, e.g. a bridge arrival on another chain). Exactly one flavor must be configured. - `channel` 'telegram' | 'api' — External-signal flavor — signal channel: `telegram` or `api`. - `approvers` string[] — External-signal flavor — authorized approver identities. Empty = the workflow owner. NOTE (v1): not yet enforced — the signal endpoint authorizes by workflow ownership only, so the owner can always approve regardless of this list. Delegated-approver enforcement (Telegram binding) is a follow-up; do not rely on this field for security yet. - `prompt` string — External-signal flavor — message shown to the approver. - `chainEvent` EventTriggerConfig — Fires when matching on-chain events are observed. - … - `timeoutSeconds` integer — Safety bound; 0 = server default (the wait is never unbounded). - `edges` Edge[] - `id` string, required - `source` string, required — Node or trigger ID where this edge starts. - `target` string, required — Node ID where this edge ends. - `inputVariables` InputVariables — Free-form key-value bag of values used to resolve `{{variable.path}}` template references inside trigger and node configs. Conventional well-known keys: `settings.runner` (smart wallet address), `settings.chainId` (chain id). camelCase keys; back-compat support for snake_case keys exists during the migration window. - `status` 'enabled' | 'disabled' | 'running' | 'completed' | 'failed', required — Lifecycle status. `enabled` means actively monitored; `disabled` is paused. `running`, `completed`, `failed` are terminal-ish states emitted during/after execution. - `startAt` integer — Unix-epoch milliseconds — workflow is inert before this time. - `expiredAt` integer — Unix-epoch milliseconds — workflow is inert after this time. - `maxExecution` integer — Cap on how many times this workflow may execute. The workflow reaches status `completed` once `executionCount` hits this value. Present and finite on every workflow created since the server began assigning a default — a create request that omits the field takes that default, and one that sends 0 or a negative is rejected, so "run forever" is not expressible. Absent on workflows created before that change and stored uncapped; those keep running without a limit, and `remainingExecutions` is likewise absent for them. - `executionCount` integer — How many times this workflow has executed so far. - `remainingExecutions` integer — Runs left before the workflow completes — `maxExecution` minus `executionCount`, floored at 0. Derived server-side so clients do not have to reproduce the arithmetic (and so an absent `executionCount` on a never-run workflow cannot be misread). Reported as 0 rather than omitted once the budget is spent. Absent only on legacy uncapped workflows, where no finite number exists. - `completionReason` 'TASK_COMPLETION_REASON_UNSPECIFIED' | 'TASK_COMPLETION_REASON_MAX_EXECUTIONS_REACHED' | 'TASK_COMPLETION_REASON_EXPIRED' — Why the workflow reached a terminal state. An exhausted execution budget and a passed expiry both produce status `completed`, so the status alone cannot distinguish them. Absent or UNSPECIFIED while the workflow is still runnable, and on workflows that terminated before this field existed. Cancellation is not represented — cancelling deletes the workflow rather than leaving a record. - `createdAt` integer — Unix-epoch milliseconds — when the workflow was first created. - `completedAt` integer — Unix-epoch milliseconds — when the workflow reached a terminal state. - `pageInfo` PageInfo, required - `hasNextPage` boolean, required - `hasPreviousPage` boolean, required - `startCursor` string — Cursor for the first item in the current page; pass to `before` for the previous page. - `endCursor` string — Cursor for the last item in the current page; pass to `after` for the next page. ## Other responses - `401` — Missing or invalid bearer token. - `429` — Rate limit exceeded. Inspect `X-RateLimit-Reset` for the next allowed request time and `Retry-After` for the seconds to wait. --- [API](https://skmtc.net/avaprotocol/apis/ava-protocol-avs-api.md) · [All operations](https://skmtc.net/avaprotocol/apis/ava-protocol-avs-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/avaprotocol/ava-protocol-avs-api/revisions/caa86e825f53/schema)