Using the Agent Tasks API🔗

The Agent Tasks API endpoints let you programmatically create, monitor, and manage Maia AI Agents' tasks. You give Maia AI Agents an instruction and they work asynchronously in the background.

The ai/agents/tasks endpoints allow you to perform the following actions:

Create a task: Give Maia AI Agents an instruction to work on. Returns the task ID you need for all subsequent actions.
List tasks: Retrieve a list of all tasks, optionally filtered by project, branch, or status.
Find the status of a task: Check the current status and details of a task.
Handle decisions: Approve tool use or answer questions when Maia AI Agents pause mid-task and ask for your input.
Read messages: Retrieve the message history for a task to follow Maia AI Agents' reasoning or collect their output.
Send a follow-up message: Send additional instructions to an existing task—for example, to give clarification, redirect Maia AI Agents, or resume them after they've stopped.
Stop a task: Stop a running task. Maia AI Agents finish what they're currently doing before stopping.
Delete a task: Permanently delete a task and all of its associated data.
Update task permissions: Replace the full set of tools Maia AI Agents are permitted to use.

A task is the overall piece of work you give Maia AI Agents to complete—comparable to opening a new chat with Maia AI Agents in Designer and sending your opening prompt. A message is an individual instruction sent within that task, comparable to continuing that same chat.

Maia AI Agents work under the identity of the user associated with the API key. This means that any changes you make using the Agent Tasks API endpoints aren't automatically visible to other project users. To review or merge the work, ask Maia AI Agents to commit and push changes to the target branch. You can either include this in your original instruction when you create the task, or send a follow-up message as part of the existing task. Each task works in isolation on its own branch, so creating a new task always starts a completely separate piece of work that isn't connected to any previous task.

Note

These endpoints currently only work with Matillion-hosted and GitHub projects.

Create a task🔗

Use this endpoint to create a new task and send Maia AI Agents an instruction to work on. A successful request returns a task ID that you use in all subsequent requests.

Request fields🔗

Field	Required	Description
Top-level fields
`message`	Yes	The instruction or question to send to the agent—your opening prompt.
`agentConfig`	Yes	Sets the project, environment, and behavior for the task—see `agentConfig` fields below.
`grantedPermissions`	No	Tools to pre-approve so the agent doesn't need to pause and ask for permission mid-task.
agentConfig fields
`name`	Yes	The agent type. Currently always `"data_engineer_agent"`.
`mode`	Yes	`"ACT"` — the agent makes changes. `"PLAN"` — the agent produces a plan only, no changes are made.
`projectId`	Yes	The ID of the Matillion project the agent will work in.
`sourceBranchName`	Yes	The branch the agent reads from. When creating a new branch, this is the branch to branch off from.
`environmentName`	Yes	The Matillion environment the agent will use when running pipelines.
`targetBranchName`	Conditional	The name of a new branch for the agent to create and write changes to. Required unless `generateBranch` is `true`.
`generateBranch`	Conditional	Set to `true` to let the agent auto-generate a branch name. Required unless `targetBranchName` is provided. Ignored if `targetBranchName` is also provided.
`graphId`	No	The ID of a Knowledge Layer service graph.
`workingDirectory`	No	A folder path within the project to scope the agent's work.
grantedPermissions fields
`toolName`	Yes	The name of a tool to pre-approve. For example, `"execute_sql"`. For a list of available tools and their `toolName` values, read Available toolsbelow.

Example request🔗

Base URL: POST /v1/ai/agents/tasks

Example request body:

{
  "message": "Build a pipeline to load sales data from S3 into Snowflake, transforming the date columns to UTC.",
  "agentConfig": {
    "name": "data_engineer_agent",
    "mode": "ACT",
    "projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "sourceBranchName": "main",
    "environmentName": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "targetBranchName": "feature/sales-pipeline"
  },
  "grantedPermissions": [
    { "toolName": "execute_sql" }
  ]
}

Example success response:

HTTP 201 Created
{
  "taskId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "status": "RUNNING",
  "agentName": "data_engineer_agent",
  "createdAt": "2026-04-08T10:23:45+00:00"
}

List tasks🔗

Use this endpoint to retrieve a list of all tasks. You can filter results by project, branch, or status.

Query parameters🔗

Parameter	Description
`projectId`	Return only tasks belonging to this project.
`branchId`	Return only tasks associated with this branch.
`status`	Return only tasks in a specific status. One of: `RUNNING`, `STOPPED`, `STOPPING`, `ERRORED`.
`page`	The zero-indexed page number to return. Default `0`.
`size`	Number of tasks to return per page. Default `20`, minimum `1`, maximum `100`.

Example request🔗

Base URL: GET /v1/ai/agents/tasks

Example success response:

HTTP 200 OK
{
  "tasks": [
    {
      "taskId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "status": "RUNNING",
      "agentName": "data_engineer_agent",
      "mode": "ACT",
      "description": "Build a pipeline to load sales data from S3 into Snowflake",
      "modifiedAt": "2026-04-08T10:25:00+00:00",
      "projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "branchId": "feature/sales-pipeline"
    }
  ],
  "page": 0,
  "size": 20,
  "total": 1
}

Find the status of a task🔗

Use this endpoint to check the current status and details of a task.

Task statuses🔗

Status	Meaning
`RUNNING`	The agent is actively working.
`STOPPING`	A stop has been requested; the agent is wrapping up.
`STOPPED`	The agent has paused—see note below.
`ERRORED`	Something went wrong. Check the task messages for details.

Warning

STOPPED means two different things depending on whether the task has pending decisions:

STOPPED + empty pendingDecisions → the agent has finished. Treat as terminal.
STOPPED + non-empty pendingDecisions → the agent is paused waiting for human input. This is not a terminal state—submit decisions to resume the task.

Checking only the status field may cause paused tasks to be incorrectly marked as completed.

Example request🔗

Base URL: GET /v1/ai/agents/tasks/{taskId}

Example success response:

HTTP 200 OK
{
  "taskId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "status": "STOPPED",
  "description": "Build a pipeline to load sales data from S3 into Snowflake",
  "createdAt": "2026-04-08T10:23:45+00:00",
  "modifiedAt": "2026-04-08T10:26:10+00:00",
  "agentConfig": {
    "name": "data_engineer_agent",
    "mode": "ACT",
    "projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "sourceBranchName": "main",
    "environmentName": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "targetBranchName": "feature/sales-pipeline"
  },
  "grantedPermissions": [
    { "toolName": "execute_sql" }
  ],
  "pendingDecisions": [
    {
      "type": "tool",
      "toolName": "execute_sql",
      "toolId": "e5f6a7b8-c9d0-1234-efab-345678901234",
      "permissionMessage": {
        "title": "Execute SQL query",
        "body": "The agent wants to run: SELECT * FROM sales LIMIT 10"
      },
      "toolInput": {
        "query": "SELECT * FROM sales LIMIT 10"
      }
    }
  ]
}

Handle decisions🔗

Use this endpoint to submit decisions on a stopped task and resume the agent. When pendingDecisions is not empty on a STOPPED task, the agent is paused waiting for your input.

There are two decision types:

Approve the use of a tool so that Maia AI Agents can use this tool to complete their task.
Answer a question that Maia AI Agents asked as part of completing their task.

Example request: Tool approval🔗

Base URL: POST /v1/ai/agents/tasks/{taskId}/decisions

{
  "decisions": [
    {
      "type": "tool",
      "id": "<toolId>",
      "approved": true,
      "scope": "ONCE"
    }
  ]
}

The id value comes from pendingDecisions[].toolId on the task. Set scope to "CONVERSATION" to pre-approve the tool for the remainder of the task—useful when the agent will call the same tool many times in a loop.

Example request: Answer a question🔗

{
  "decisions": [
    {
      "type": "question",
      "id": "<questionId>",
      "answers": [
        {
          "questionIndex": 0,
          "selectedOptions": ["yes"]
        }
      ]
    }
  ]
}

Example success response:

HTTP 202 Accepted
{
  "pendingDecisions": []
}

Read messages🔗

Use this endpoint to retrieve the message history for a task and follow the agent's reasoning or collect its output. This is the primary way to see what the agent is doing and read its results.

Query parameters🔗

Parameter	Description
`limit`	Maximum messages per page. Default 25, maximum 1000.
`paginationToken`	Pass the value from the previous response's `more` field to retrieve the next page.

Example request🔗

Base URL: GET /v1/ai/agents/tasks/{taskId}/messages

The response includes a results array of events ordered chronologically, and a more field containing the pagination token for the next page. When more is absent and the task status is STOPPED or ERRORED, there are no more events to retrieve.

Send a follow-up message🔗

Use this endpoint to send an additional instruction to an existing task—for example, to give clarification, redirect the agent, or resume it after it has stopped.

Request fields🔗

Field	Required	Description
Top-level fields
`message`	Yes	The follow-up instruction or question to send to the agent.
`grantedPermissions`	No	Additional tools to grant. Added on top of any permissions already granted to the task.
`agentConfig`	No	Optional overrides to the agent's behavior from this message onward. Only `mode` and `targetBranchName` can be overridden—see `agentConfig` fields below.
agentConfig fields
`name`	Yes	Must be `"data_engineer_agent"`.
`mode`	No	Override the agent mode: `"ACT"` to make changes, `"PLAN"` to produce a plan only.
`targetBranchName`	No	Override the branch the agent writes changes to.

Example request🔗

Base URL: POST /v1/ai/agents/tasks/{taskId}/messages

Example request body:

{
  "message": "Also add a step to handle null values in the date columns before transforming.",
  "agentConfig": {
    "name": "data_engineer_agent",
    "mode": "ACT"
  }
}

Example success response:

HTTP 202 Accepted
{
  "taskId": "c3d4e5f6-a7b8-9012-cdef-123456789012"
}

Stop a task🔗

Use this endpoint to stop a task that is running. Maia AI Agents finish what they are currently doing before stopping.

Use GET /v1/ai/agents/tasks/{taskId} to monitor the task status until it reaches STOPPED before attempting further operations on the task. Once stopped, you can resume the task by sending it a new message, or delete it.

Example request🔗

Base URL: POST /v1/ai/agents/tasks/{taskId}/stop

No request body is required.

Example success response:

HTTP 204 No Content

Delete a task🔗

Use this endpoint to permanently delete a task and all of its associated data. Deleting a task means that you won't have an audit trail for any changes that Maia AI Agents made as part of the deleted task.

Warning

You can't delete a task with a status of RUNNING—the request will fail with a 409 Conflict. Stop the task first and wait for it to reach STOPPED before deleting.

Example request🔗

Base URL: DELETE /v1/ai/agents/tasks/{taskId}

Example success response:

HTTP 204 No Content

Update task permissions🔗

Use this endpoint to replace the full set of tools the agent has been granted permission to use. This is a complete replacement—whatever you send becomes the new list. For a list of available tools and their toolName values, read Available tools below.

Note

This endpoint replaces the full permission set, not individual permissions. To add a single permission, re-send the complete list including the new entry. Pass an empty list ([]) to clear all permissions.

Example request🔗

Base URL: PUT /v1/ai/agents/tasks/{taskId}/permissions

Example request body:

{
  "grantedPermissions": [
    { "toolName": "execute_sql" },
    { "toolName": "read_file" }
  ]
}

Example success response:

HTTP 200 OK
{
  "taskId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "grantedPermissions": [
    { "toolName": "execute_sql" },
    { "toolName": "read_file" }
  ]
}

Available tools🔗

The following table lists all tools that Maia AI Agents can use as part of a task. Use the names in the Tool name column as the value of the toolName field when creating a task or updating task permissions.

Tool name	Description
`git_push`	Pushes committed changes to the remote Git repository.
`git_commit`	Commits staged changes to the local Git repository.
`run_pipeline`	Triggers execution of a pipeline.
`query_warehouse`	Executes a read-only SQL query against the data warehouse.
`edit_file`	Edits file content via find-and-replace.
`create_file`	Creates a new file.
`delete_file`	Permanently deletes a file.
`copy_file`	Copies a file or folder to a new location.
`rename_file`	Renames or moves a file or folder.
`ask_user_question`	Asks the user structured questions with multiple-choice options.
`sample_component`	Samples rows from an existing pipeline component.
`enter_plan_mode`	Switches the agent to PLAN mode for research and design.
`exit_plan_mode`	Presents a plan for user review and switches back to ACT mode.
`create_custom_connector`	Initiates the custom connector creation flow for unsupported data sources.