Using the Agent Tasks API

The Agent Tasks API endpoints let you programmatically create, monitor, and manage ’ tasks. You give 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 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 pause mid-task and ask for your input.
Read messages: Retrieve the message history for a task to follow ’ reasoning or collect their output.
Send a follow-up message: Send additional instructions to an existing task—for example, to give clarification, redirect , or resume them after they’ve stopped.
Stop a task: Stop a running task. 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 are permitted to use.

A task is the overall piece of work you give to complete—comparable to opening a new chat with in and sending your opening prompt. A message is an individual instruction sent within that task, comparable to continuing that same chat. 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 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.

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

Create a task

Use this endpoint to create a new task and send 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 tools below.

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.

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 can use this tool to complete their task.
Answer a question that 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. 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 made as part of the deleted task.

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.

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 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.

Overview

Endpoints

Guides

Create a task

Request fields

Example request

List tasks

Query parameters

Example request

Find the status of a task

Task statuses

Example request

Handle decisions

Example request: Tool approval

Example request: Answer a question

Read messages

Query parameters

Example request

Send a follow-up message

Request fields

Example request

Stop a task

Example request

Delete a task

Example request

Update task permissions

Example request

Available tools

Overview

Endpoints

Guides

Documentation Index

​Create a task

​Request fields

​Example request

​List tasks

​Query parameters

​Example request

​Find the status of a task

​Task statuses

​Example request

​Handle decisions

​Example request: Tool approval

​Example request: Answer a question

​Read messages

​Query parameters

​Example request

​Send a follow-up message

​Request fields

​Example request

​Stop a task

​Example request

​Delete a task

​Example request

​Update task permissions

​Example request

​Available tools

Create a task

Request fields

Example request

List tasks

Query parameters

Example request

Find the status of a task

Task statuses

Example request

Handle decisions

Example request: Tool approval

Example request: Answer a question

Read messages

Query parameters

Example request

Send a follow-up message

Request fields

Example request

Stop a task

Example request

Delete a task

Example request

Update task permissions

Example request

Available tools