Tasks
Every operation in this group: what it accepts, what it returns and the errors it can answer with.
Operations
Tasks let the assistant work by itself: a task is an instruction in plain words that runs on a schedule, when mail arrives, or when asked. Each run reads and acts through the same tools the assistant uses in a chat, keeps a step by step record, and stops to ask a person before anything it was not allowed to do alone. A run never reaches billing, members, roles, domains, rules, keys or webhooks, and it treats what emails say as information, never as instructions.
GET/tasks
List tasks
Every task of the workspace, the most recently changed first. A task works across every address of the workspace, so a key or an app limited to particular addresses or domains is refused with capability_unsupported, and an app has to act for somebody who reaches every address.
Requires the tasks:read and threads:read and emails:read scopes.
Query parameters
statusstringOnly tasks in this state:
activeorpaused. Left out, both are listed.One of"active""paused"limitintegerPage size, from 1 to 100. The server defaults to 25.
At least 1At most 100cursorstringThe
nextCursorof the previous page, passed back as it came. Leave it out for the first page.1 to 256 characters
Returns
A page of tasks.
Errors
- 400
The errors every operation can return401403404422500Error catalog
Also available in
- TypeScript
tasks.list()tasks.listAll()tasks.iterate()- Python
tasks.list()tasks.list_all()tasks.iterate()- Ruby
tasks.listtasks.list_alltasks.iterate- PHP
tasks->listtasks->listAlltasks->iterate- Go
Tasks.ListTasks.ListAllTasks.Iterate- Java
tasks().listtasks().listAlltasks().iterate- C#
Tasks.ListAsyncTasks.ListAllAsyncTasks.IterateAsync- CLI
openemail tasks list- MCP
listTasks
POST/tasks
Create a task
Saves an instruction for the assistant with what starts it and how much it may do alone. A schedule task gets its first run time at once, a mail task starts with the next message that matches, and a manual task waits to be run. A task acts with what its caller holds: besides tasks:write the request needs threads:read, threads:write, emails:read, emails:send, labels:write and the read and write scopes of every toolkit the task names. A workspace runs 1 active task on Free, 5 on Starter and 25 on Business, with no cap on Enterprise, and holds at most 100 tasks. A task works across every address of the workspace, so a key or an app limited to particular addresses or domains is refused with capability_unsupported, and an app has to act for somebody who reaches every address.
Requires the tasks:write and threads:read and threads:write and emails:read and emails:send and labels:write scopes.
Request body
namestringRequiredWhat the task is called in the app.
1 to 120 charactersinstructionstringRequiredWhat the assistant should do, in plain words, as you would tell a person. It is the only instruction the run follows: text inside emails is read, never obeyed.
1 to 8000 characterstriggerobjectRequiredWhat starts a run: a schedule, new mail, or only somebody asking.
kindstringRequiredscheduleruns on a clock,mailruns when a message arrives, andmanualruns only when started by hand or through the API.One of"schedule""mail""manual"scheduleobjectWhen a
scheduletask runs. Needed for that kind and ignored for the others.Can be nullcadencestringRequiredhourlyruns everyeveryHourshours atminute,dailyruns athour:minuteon each ofweekdays, andmonthlyruns athour:minuteonmonthDay.One of"hourly""daily""monthly"everyHoursintegerFor
hourly: how many hours lie between runs, counted from midnight in the time zone.At least 1At most 12Default1hourintegerThe hour of the day, 0 to 23, in the time zone of the schedule.
At least 0At most 23Default8minuteintegerThe minute of the hour, 0 to 59.
At least 0At most 59Default0weekdaysinteger[]For
daily: the days it runs, 0 for Sunday to 6 for Saturday. Left out, it runs every day.1 to 7 itemsDefault[0,1,2,3,4,5,6]monthDayintegerFor
monthly: the day of the month, 1 to 28.At least 1At most 28Default1timezonestringAn IANA time zone such as
Europe/Berlin. The schedule follows its clock changes.1 to 64 charactersDefault"UTC"
mailobjectWhich arriving mail starts a
mailtask. Left out, every message that reaches an inbox does.Can be nulladdressesstring[]Start only for mail delivered to one of these addresses of the workspace. Empty means every address.
Up to 25 itemsDefault[]fromContainsstringStart only when the sender address contains this text, whatever the case.
Can be nullUp to 200 characterssubjectContainsstringStart only when the subject contains this text, whatever the case.
Can be nullUp to 200 characters
autonomystringasksends every change to a person to approve.organizelets the run label, archive, bin, snooze, draft, take notes and keep contacts by itself, and email the addresses of the workspace.replyalso lets it answer an email without asking, as long as it adds no recipients and the task does not useconnectors. Anything else always waits for approval, and so does every change in a connected app.One of"ask""organize""reply"toolkitsstring[]Extra groups of tools the run may use beyond reading and organising mail, such as
contacts,calendar,knowledge,weborconnectors, which lets it use the apps connected for the workspace. A run can never reach billing, members, domains, rules, keys or webhooks.Up to 15 itemsmodelstringstandardis the everyday model.advancedreasons better over long jobs and costs ten AI actions where the standard one costs one.One of"standard""advanced"notifystringattentionnotifies the workspace owner when a run waits for approval or fails,alwaysalso when it finishes, andneverstays silent.One of"always""attention""never"maxRunsPerDayintegerThe most runs the task may start in any 24 hours, however often its trigger fires.
At least 1At most 500maxStepsintegerThe most model steps one run may take before it has to write its report.
At least 1At most 60pausedbooleanCreate the task paused, so it does not run until it is resumed.
Returns
The task as it is stored.
Errors
- 403
The key lacks a scope.
task_active_limit_reached: the plan covers no more active tasks.task_limit_reached: the workspace holds as many tasks as it may.- 422
invalid_parameter: a field is missing or malformed.invalid_task: the trigger lacks its schedule, the time zone is unknown, or a toolkit is not one a task may use.capability_unsupported: the key or app is limited to particular addresses.
The errors every operation can return400401404500Error catalog
Also available in
- TypeScript
tasks.create()- Python
tasks.create()- Ruby
tasks.create- PHP
tasks->create- Go
Tasks.Create- Java
tasks().create- C#
Tasks.CreateAsync- CLI
openemail tasks create- MCP
createTask
GET/tasks/{id}
Read a task
One task with its trigger, its limits and when it runs next. A task works across every address of the workspace, so a key or an app limited to particular addresses or domains is refused with capability_unsupported, and an app has to act for somebody who reaches every address.
Requires the tasks:read and threads:read and emails:read scopes.
Path parameters
idstringRequiredThe task, such as
tsk_5c1e9a7b3d2f48e6a0b4c7d1, asGET /taskslists it.
Returns
The task.
Errors
- 404
task_not_found: no task in this workspace has that id.
The errors every operation can return400401403422500Error catalog
Also available in
- TypeScript
tasks.get()- Python
tasks.get()- Ruby
tasks.get- PHP
tasks->get- Go
Tasks.Get- Java
tasks().get- C#
Tasks.GetAsync- CLI
openemail tasks get- MCP
getTask
PATCH/tasks/{id}
Update a task
Changes what a task does, what starts it or how much it may do alone. Send only what changes. A new trigger replaces the old one whole, and a schedule change moves the next run. Runs already started keep the settings they began with. A task acts with what its caller holds: besides tasks:write the request needs threads:read, threads:write, emails:read, emails:send, labels:write and the read and write scopes of every toolkit the task names.
Requires the tasks:write and threads:read and threads:write and emails:read and emails:send and labels:write scopes.
Path parameters
idstringRequiredThe task, such as
tsk_5c1e9a7b3d2f48e6a0b4c7d1, asGET /taskslists it.
Request body
namestringWhat the task is called in the app.
1 to 120 charactersinstructionstringWhat the assistant should do, in plain words, as you would tell a person. It is the only instruction the run follows: text inside emails is read, never obeyed.
1 to 8000 characterstriggerobjectWhat starts a run: a schedule, new mail, or only somebody asking.
kindstringRequiredscheduleruns on a clock,mailruns when a message arrives, andmanualruns only when started by hand or through the API.One of"schedule""mail""manual"scheduleobjectWhen a
scheduletask runs. Needed for that kind and ignored for the others.Can be nullcadencestringRequiredhourlyruns everyeveryHourshours atminute,dailyruns athour:minuteon each ofweekdays, andmonthlyruns athour:minuteonmonthDay.One of"hourly""daily""monthly"everyHoursintegerFor
hourly: how many hours lie between runs, counted from midnight in the time zone.At least 1At most 12Default1hourintegerThe hour of the day, 0 to 23, in the time zone of the schedule.
At least 0At most 23Default8minuteintegerThe minute of the hour, 0 to 59.
At least 0At most 59Default0weekdaysinteger[]For
daily: the days it runs, 0 for Sunday to 6 for Saturday. Left out, it runs every day.1 to 7 itemsDefault[0,1,2,3,4,5,6]monthDayintegerFor
monthly: the day of the month, 1 to 28.At least 1At most 28Default1timezonestringAn IANA time zone such as
Europe/Berlin. The schedule follows its clock changes.1 to 64 charactersDefault"UTC"
mailobjectWhich arriving mail starts a
mailtask. Left out, every message that reaches an inbox does.Can be nulladdressesstring[]Start only for mail delivered to one of these addresses of the workspace. Empty means every address.
Up to 25 itemsDefault[]fromContainsstringStart only when the sender address contains this text, whatever the case.
Can be nullUp to 200 characterssubjectContainsstringStart only when the subject contains this text, whatever the case.
Can be nullUp to 200 characters
autonomystringasksends every change to a person to approve.organizelets the run label, archive, bin, snooze, draft, take notes and keep contacts by itself, and email the addresses of the workspace.replyalso lets it answer an email without asking, as long as it adds no recipients and the task does not useconnectors. Anything else always waits for approval, and so does every change in a connected app.One of"ask""organize""reply"toolkitsstring[]Extra groups of tools the run may use beyond reading and organising mail, such as
contacts,calendar,knowledge,weborconnectors, which lets it use the apps connected for the workspace. A run can never reach billing, members, domains, rules, keys or webhooks.Up to 15 itemsmodelstringstandardis the everyday model.advancedreasons better over long jobs and costs ten AI actions where the standard one costs one.One of"standard""advanced"notifystringattentionnotifies the workspace owner when a run waits for approval or fails,alwaysalso when it finishes, andneverstays silent.One of"always""attention""never"maxRunsPerDayintegerThe most runs the task may start in any 24 hours, however often its trigger fires.
At least 1At most 500maxStepsintegerThe most model steps one run may take before it has to write its report.
At least 1At most 60
Returns
The task after the change.
Errors
- 404
task_not_found: no task in this workspace has that id.- 422
invalid_parameter: nothing to change was sent or a field is malformed.invalid_task: the trigger, the time zone or a toolkit is not valid.
The errors every operation can return400401403500Error catalog
Also available in
- TypeScript
tasks.update()- Python
tasks.update()- Ruby
tasks.update- PHP
tasks->update- Go
Tasks.Update- Java
tasks().update- C#
Tasks.UpdateAsync- CLI
openemail tasks update- MCP
updateTask
DELETE/tasks/{id}
Delete a task
Deletes a task for good, with every run it made and their records. A run in flight is stopped and its open approval requests are closed.
Requires the tasks:write scope.
Path parameters
idstringRequiredThe task, such as
tsk_5c1e9a7b3d2f48e6a0b4c7d1, asGET /taskslists it.
Returns
Deleted.
Errors
- 404
task_not_found: no task in this workspace has that id.
The errors every operation can return400401403422500Error catalog
Also available in
- TypeScript
tasks.delete()- Python
tasks.delete()- Ruby
tasks.delete- PHP
tasks->delete- Go
Tasks.Delete- Java
tasks().delete- C#
Tasks.DeleteAsync- CLI
openemail tasks delete- MCP
deleteTask
POST/tasks/{id}/pause
Pause a task
Stops a task from starting new runs. A run already going carries on, and its approval requests can still be answered.
Requires the tasks:write scope.
Path parameters
idstringRequiredThe task, such as
tsk_5c1e9a7b3d2f48e6a0b4c7d1, asGET /taskslists it.
Returns
The task, paused.
Errors
- 404
task_not_found: no task in this workspace has that id.
The errors every operation can return400401403422500Error catalog
Also available in
- TypeScript
tasks.pause()- Python
tasks.pause()- Ruby
tasks.pause- PHP
tasks->pause- Go
Tasks.Pause- Java
tasks().pause- C#
Tasks.PauseAsync- CLI
openemail tasks pause- MCP
pauseTask
POST/tasks/{id}/resume
Resume a task
Turns a paused task back on, whoever or whatever paused it, clears its failure count and gives a schedule task its next run time. A task acts with what its caller holds: besides tasks:write the request needs threads:read, threads:write, emails:read, emails:send, labels:write and the read and write scopes of every toolkit the task names. A workspace runs 1 active task on Free, 5 on Starter and 25 on Business, with no cap on Enterprise, and holds at most 100 tasks.
Requires the tasks:write and threads:read and threads:write and emails:read and emails:send and labels:write scopes.
Path parameters
idstringRequiredThe task, such as
tsk_5c1e9a7b3d2f48e6a0b4c7d1, asGET /taskslists it.
Returns
The task, active again.
Errors
- 403
The key lacks a scope.
task_active_limit_reached: the plan covers no more active tasks.- 404
task_not_found: no task in this workspace has that id.
The errors every operation can return400401422500Error catalog
Also available in
- TypeScript
tasks.resume()- Python
tasks.resume()- Ruby
tasks.resume- PHP
tasks->resume- Go
Tasks.Resume- Java
tasks().resume- C#
Tasks.ResumeAsync- CLI
openemail tasks resume- MCP
resumeTask
POST/tasks/{id}/run
Run a task now
Starts a run of a task at once, whatever its trigger and whether or not it is paused. The answer is the run as it was queued: read it again with GET /task-runs/{id} to follow it. A task acts with what its caller holds: besides tasks:write the request needs threads:read, threads:write, emails:read, emails:send, labels:write and the read and write scopes of every toolkit the task names.
Requires the tasks:write and threads:read and threads:write and emails:read and emails:send and labels:write scopes.
Path parameters
idstringRequiredThe task, such as
tsk_5c1e9a7b3d2f48e6a0b4c7d1, asGET /taskslists it.
Returns
The run, queued.
Errors
- 404
task_not_found: no task in this workspace has that id.- 409
task_run_limit_reached: the task has run as often as it may today.
The errors every operation can return400401403422500Error catalog
Also available in
- TypeScript
tasks.run()- Python
tasks.run()- Ruby
tasks.run- PHP
tasks->run- Go
Tasks.Run- Java
tasks().run- C#
Tasks.RunAsync- CLI
openemail tasks run- MCP
runTask
GET/task-runs
List task runs
Every run in the workspace, newest first, or the runs of one task with taskId. Runs are kept for 90 days. A task works across every address of the workspace, so a key or an app limited to particular addresses or domains is refused with capability_unsupported, and an app has to act for somebody who reaches every address.
Requires the tasks:read and threads:read and emails:read scopes.
Query parameters
taskIdstringOnly the runs of this task, by its id. Left out, the runs of every task and the one-off runs are listed.
1 to 64 charactersstatusstringOnly runs in this state:
queued,running,waiting,done,failedorcancelled.One of"queued""running""waiting""done""failed""cancelled"limitintegerPage size, from 1 to 100. The server defaults to 25.
At least 1At most 100cursorstringThe
nextCursorof the previous page, passed back as it came. Leave it out for the first page.1 to 256 characters
Returns
A page of runs.
Errors
- 400
The errors every operation can return401403404422500Error catalog
Also available in
- TypeScript
tasks.listRuns()tasks.listAllRuns()tasks.iterateRuns()- Python
tasks.list_runs()tasks.list_all_runs()tasks.iterate_runs()- Ruby
tasks.list_runstasks.list_all_runstasks.iterate_runs- PHP
tasks->listRunstasks->listAllRunstasks->iterateRuns- Go
Tasks.ListRunsTasks.ListAllRunsTasks.IterateRuns- Java
tasks().listRunstasks().listAllRunstasks().iterateRuns- C#
Tasks.ListRunsAsyncTasks.ListAllRunsAsyncTasks.IterateRunsAsync- CLI
openemail tasks list-runs- MCP
listTaskRuns
POST/task-runs
Start a one-off run
Hands the assistant one job to do in the background, with no task saved: a long tidy-up, a report, or anything that should not wait on an open chat. A workspace starts at most 100 of these a day. A task acts with what its caller holds: besides tasks:write the request needs threads:read, threads:write, emails:read, emails:send, labels:write and the read and write scopes of every toolkit the task names. A task works across every address of the workspace, so a key or an app limited to particular addresses or domains is refused with capability_unsupported, and an app has to act for somebody who reaches every address.
Requires the tasks:write and threads:read and threads:write and emails:read and emails:send and labels:write scopes.
Request body
instructionstringRequiredWhat the assistant should do, in plain words, as you would tell a person. It is the only instruction the run follows: text inside emails is read, never obeyed.
1 to 8000 charactersautonomystringasksends every change to a person to approve.organizelets the run label, archive, bin, snooze, draft, take notes and keep contacts by itself, and email the addresses of the workspace.replyalso lets it answer an email without asking, as long as it adds no recipients and the task does not useconnectors. Anything else always waits for approval, and so does every change in a connected app.One of"ask""organize""reply"toolkitsstring[]Extra groups of tools the run may use beyond reading and organising mail, such as
contacts,calendar,knowledge,weborconnectors, which lets it use the apps connected for the workspace. A run can never reach billing, members, domains, rules, keys or webhooks.Up to 15 itemsmodelstringstandardis the everyday model.advancedreasons better over long jobs and costs ten AI actions where the standard one costs one.One of"standard""advanced"maxStepsintegerThe most model steps one run may take before it has to write its report.
At least 1At most 60threadIdstringA conversation to hand the run as its starting point, as
GET /threadslists it.1 to 255 characters
Returns
The run, queued.
Errors
- 409
task_run_limit_reached: the workspace has started as many as it may today.- 422
invalid_parameter: a field is missing or malformed.invalid_task: a toolkit is not one a run may use.
The errors every operation can return400401403404500Error catalog
Also available in
GET/task-runs/{id}
Read a task run
One run with its report, every step it took, the tools it called with what they answered, and its approval requests. A task works across every address of the workspace, so a key or an app limited to particular addresses or domains is refused with capability_unsupported, and an app has to act for somebody who reaches every address.
Requires the tasks:read and threads:read and emails:read scopes.
Path parameters
idstringRequiredThe run, such as
run_2b8d4f6a1c3e5079b6d8f0a2, asGET /task-runslists it.
Returns
The run.
Errors
- 404
task_run_not_found: no run in this workspace has that id.
The errors every operation can return400401403422500Error catalog
Also available in
- TypeScript
tasks.getRun()- Python
tasks.get_run()- Ruby
tasks.get_run- PHP
tasks->getRun- Go
Tasks.GetRun- Java
tasks().getRun- C#
Tasks.GetRunAsync- CLI
openemail tasks get-run- MCP
getTaskRun
POST/task-runs/{id}/cancel
Cancel a task run
Stops a run that is queued, running or waiting for approval, and closes its open approval requests. What the run already did stays done.
Requires the tasks:write scope.
Path parameters
idstringRequiredThe run, such as
run_2b8d4f6a1c3e5079b6d8f0a2, asGET /task-runslists it.
Returns
The run, cancelled.
Errors
- 404
task_run_not_found: no run in this workspace has that id.- 409
task_run_finished: the run has already ended.
The errors every operation can return400401403422500Error catalog
Also available in
GET/task-approvals
List approval requests
What runs are waiting for a person to allow, newest first: the tool the run wants to call and the exact arguments it would call it with. A request waits 7 days, then expires and the run carries on without it. A task works across every address of the workspace, so a key or an app limited to particular addresses or domains is refused with capability_unsupported, and an app has to act for somebody who reaches every address.
Requires the tasks:read and threads:read and emails:read scopes.
Query parameters
statusstringOnly requests in this state:
pending,approved,denied,expiredorcancelled. Left out, the list holds the ones still pending.One of"pending""approved""denied""expired""cancelled"runIdstringOnly the requests of this run, by its id.
1 to 64 characterstaskIdstringOnly the requests of the runs of this task, by its id.
1 to 64 characterslimitintegerPage size, from 1 to 100. The server defaults to 25.
At least 1At most 100cursorstringThe
nextCursorof the previous page, passed back as it came. Leave it out for the first page.1 to 256 characters
Returns
A page of approval requests.
Errors
- 400
The errors every operation can return401403404422500Error catalog
Also available in
- TypeScript
tasks.listApprovals()tasks.listAllApprovals()tasks.iterateApprovals()- Python
tasks.list_approvals()tasks.list_all_approvals()tasks.iterate_approvals()- Ruby
tasks.list_approvalstasks.list_all_approvalstasks.iterate_approvals- PHP
tasks->listApprovalstasks->listAllApprovalstasks->iterateApprovals- Go
Tasks.ListApprovalsTasks.ListAllApprovalsTasks.IterateApprovals- Java
tasks().listApprovalstasks().listAllApprovalstasks().iterateApprovals- C#
Tasks.ListApprovalsAsyncTasks.ListAllApprovalsAsyncTasks.IterateApprovalsAsync- CLI
openemail tasks list-approvals- MCP
listTaskApprovals
GET/task-approvals/{id}
Read an approval request
One approval request. A task works across every address of the workspace, so a key or an app limited to particular addresses or domains is refused with capability_unsupported, and an app has to act for somebody who reaches every address.
Requires the tasks:read and threads:read and emails:read scopes.
Path parameters
idstringRequiredThe approval request, such as
apr_9f3a1c5e7b2d4608a1c3e5f7, asGET /task-approvalslists it.
Returns
The approval request.
Errors
- 404
task_approval_not_found: no approval request in this workspace has that id.
The errors every operation can return400401403422500Error catalog
Also available in
POST/task-approvals/{id}/approve
Approve a request
Lets the run do what it asked for, with the arguments the request shows. For a send or a reply, subject and body replace what the run wrote. The run picks up again once every request of its step is answered. A task acts with what its caller holds: besides tasks:write the request needs threads:read, threads:write, emails:read, emails:send, labels:write and the read and write scopes of every toolkit the task names.
Requires the tasks:write and threads:read and threads:write and emails:read and emails:send and labels:write scopes.
Path parameters
idstringRequiredThe approval request, such as
apr_9f3a1c5e7b2d4608a1c3e5f7, asGET /task-approvalslists it.
Request body
subjectstringFor a send or a reply: the subject to use instead of the one the run wrote.
1 to 998 charactersbodystringFor a send or a reply: the words to send instead of the ones the run wrote.
1 to 100000 characters
Returns
The request, approved.
Errors
- 404
task_approval_not_found: no approval request in this workspace has that id.- 409
task_approval_decided: the request was already answered, has expired, or its run has ended.
The errors every operation can return400401403422500Error catalog
Also available in
- TypeScript
tasks.approve()- Python
tasks.approve()- Ruby
tasks.approve- PHP
tasks->approve- Go
Tasks.Approve- Java
tasks().approve- C#
Tasks.ApproveAsync- CLI
openemail tasks approve- MCP
approveTaskApproval
POST/task-approvals/{id}/deny
Deny a request
Refuses what the run asked for. The run is told, does not try again, and carries on with the rest of its task.
Requires the tasks:write scope.
Path parameters
idstringRequiredThe approval request, such as
apr_9f3a1c5e7b2d4608a1c3e5f7, asGET /task-approvalslists it.
Returns
The request, denied.
Errors
- 404
task_approval_not_found: no approval request in this workspace has that id.- 409
task_approval_decided: the request was already answered, has expired, or its run has ended.
The errors every operation can return400401403422500Error catalog
Also available in
- TypeScript
tasks.deny()- Python
tasks.deny()- Ruby
tasks.deny- PHP
tasks->deny- Go
Tasks.Deny- Java
tasks().deny- C#
Tasks.DenyAsync- CLI
openemail tasks deny- MCP
denyTaskApproval
Objects
DeletedTaskobject
objectstringRequired- One of
"task" idstringRequireddeletedbooleanRequired- One of
true
Taskobject
objectstringRequired- One of
"task" idstringRequiredThe id, which starts with
tsk_.namestringRequiredWhat the task is called in the app.
instructionstringRequiredWhat the assistant should do, in plain words, as you would tell a person. It is the only instruction the run follows: text inside emails is read, never obeyed.
statusstringRequiredWhether the task starts runs. A paused task can still be run by hand.
One of"active""paused"pausedReasonstringRequiredWhy a paused task is paused:
userwhen somebody paused it,failuresafter 5 failed runs in a row, andplan_limitwhen the plan no longer covers it.Can be nullOne of"user""failures""plan_limit"triggerTaskTriggerRequiredautonomystringRequiredasksends every change to a person to approve.organizelets the run label, archive, bin, snooze, draft, take notes and keep contacts by itself, and email the addresses of the workspace.replyalso lets it answer an email without asking, as long as it adds no recipients and the task does not useconnectors. Anything else always waits for approval, and so does every change in a connected app.One of"ask""organize""reply"toolkitsstring[]RequiredExtra groups of tools the run may use beyond reading and organising mail, such as
contacts,calendar,knowledge,weborconnectors, which lets it use the apps connected for the workspace. A run can never reach billing, members, domains, rules, keys or webhooks.One of"contacts""audiences""templates""tracking""translate""files""notes""drafts""sent""insights""subscriptions""calendar""knowledge""connectors""web"modelstringRequiredstandardis the everyday model.advancedreasons better over long jobs and costs ten AI actions where the standard one costs one.One of"standard""advanced"notifystringRequiredattentionnotifies the workspace owner when a run waits for approval or fails,alwaysalso when it finishes, andneverstays silent.One of"always""attention""never"maxRunsPerDayintegerRequiredThe most runs the task may start in any 24 hours, however often its trigger fires.
maxStepsintegerRequiredThe most model steps one run may take before it has to write its report.
nextRunAtstringRequiredWhen a
scheduletask runs next. Null for the other kinds and while paused.Can be nullFormatdate-timeheldUntilstringRequiredSet when the workspace ran out of AI actions for the day: the task starts nothing until then.
Can be nullFormatdate-timelastRunAtstringRequiredWhen the last run of the task ended.
Can be nullFormatdate-timelastRunStatusstringRequiredHow the last run ended.
Can be nullOne of"queued""running""waiting""done""failed""cancelled"runCountintegerRequiredHow many runs the task has started.
At least 0pendingApprovalsintegerRequiredHow many approval requests of the task wait for an answer.
At least 0chatIdstringRequiredThe assistant conversation the task was created in, as
GET /chatslists it. Null for a task made anywhere else: in the Tasks page, over the API or by an MCP client.Can be nullcreatedAtstringRequiredWhen the task was created.
Formatdate-timeupdatedAtstringRequiredWhen the task last changed or last ran.
Formatdate-time
TaskApprovalobject
objectstringRequired- One of
"task_approval" idstringRequiredThe id, which starts with
apr_.runIdstringRequiredThe run that asked.
taskIdstringRequiredThe task of that run, or null for a one-off run.
Can be nulltaskNamestringRequired- Can be null
toolstringRequiredThe tool the run wants to call.
summarystringRequiredOne line that says what would happen.
argsobjectRequiredThe exact arguments the tool would be called with. A reply shows the recipients worked out from the message it answers.
statusstringRequired- One of
"pending""approved""denied""expired""cancelled" createdAtstringRequiredWhen the run asked.
Formatdate-timeexpiresAtstringRequiredWhen the request stops waiting.
Formatdate-timedecidedAtstringRequiredWhen it was answered.
Can be nullFormatdate-time
TaskApprovalListobject
objectstring- One of
"list" dataTaskApproval[]hasMorebooleanTrue when another page follows. Pass
nextCursorback ascursorto read it.nextCursorstringAn opaque cursor for the next page, or null on the last page. Pass it back unchanged.
Can be null
TaskListobject
objectstring- One of
"list" dataTask[]hasMorebooleanTrue when another page follows. Pass
nextCursorback ascursorto read it.nextCursorstringAn opaque cursor for the next page, or null on the last page. Pass it back unchanged.
Can be null
TaskRunobject
objectstringRequired- One of
"task_run" idstringRequiredThe id, which starts with
run_.taskIdstringRequiredThe task the run belongs to, or null for a one-off run.
Can be nulltaskNamestringRequiredThe name of that task.
Can be nulltriggerstringRequiredWhat started the run.
One of"schedule""mail""manual"threadIdstringRequiredThe conversation whose new message started the run, or the one a one-off run was handed.
Can be nullstatusstringRequiredqueueduntil a runner picks it up,runningwhile it works,waitingwhile an approval request is open, thendone,failedorcancelled.One of"queued""running""waiting""done""failed""cancelled"instructionstringRequiredThe instruction the run started with, kept as it was then.
autonomystringRequired- One of
"ask""organize""reply" modelstringRequired- One of
"standard""advanced" stepsintegerRequiredHow many times the model was asked what to do next.
At least 0toolCallsintegerRequiredHow many tool calls ran.
At least 0actionsintegerRequiredHow many AI actions the run has cost the workspace.
At least 0resultstringRequiredThe report the run wrote when it finished.
Can be nullerrorstringRequiredWhy a failed run failed:
ai_limitwhen the workspace ran out of AI actions for the day,ai_unavailablewhen AI is not set up, andattemptsorno_progresswhen it kept failing or stood still.Can be nullOne of"ai_limit""ai_unavailable""no_progress""attempts"errorDetailstringRequiredA sentence about the failure.
Can be nullpendingApprovalsintegerRequiredHow many approval requests of the run wait for an answer.
At least 0chatIdstringRequiredThe assistant conversation the run belongs to: the one that started it, or else the one its task was created in. Null when neither came from a conversation. The app shows the run in that conversation.
Can be nullcreatedAtstringRequiredWhen the run was queued.
Formatdate-timeupdatedAtstringRequiredWhen the run last changed: a step it took, an approval it started waiting for, or its end.
Formatdate-timestartedAtstringRequiredWhen a runner first picked it up.
Can be nullFormatdate-timefinishedAtstringRequiredWhen it ended.
Can be nullFormatdate-time
TaskRunDetailobject
objectstringRequired- One of
"task_run" idstringRequiredThe id, which starts with
run_.taskIdstringRequiredThe task the run belongs to, or null for a one-off run.
Can be nulltaskNamestringRequiredThe name of that task.
Can be nulltriggerstringRequiredWhat started the run.
One of"schedule""mail""manual"threadIdstringRequiredThe conversation whose new message started the run, or the one a one-off run was handed.
Can be nullstatusstringRequiredqueueduntil a runner picks it up,runningwhile it works,waitingwhile an approval request is open, thendone,failedorcancelled.One of"queued""running""waiting""done""failed""cancelled"instructionstringRequiredThe instruction the run started with, kept as it was then.
autonomystringRequired- One of
"ask""organize""reply" modelstringRequired- One of
"standard""advanced" stepsintegerRequiredHow many times the model was asked what to do next.
At least 0toolCallsintegerRequiredHow many tool calls ran.
At least 0actionsintegerRequiredHow many AI actions the run has cost the workspace.
At least 0resultstringRequiredThe report the run wrote when it finished.
Can be nullerrorstringRequiredWhy a failed run failed:
ai_limitwhen the workspace ran out of AI actions for the day,ai_unavailablewhen AI is not set up, andattemptsorno_progresswhen it kept failing or stood still.Can be nullOne of"ai_limit""ai_unavailable""no_progress""attempts"errorDetailstringRequiredA sentence about the failure.
Can be nullpendingApprovalsintegerRequiredHow many approval requests of the run wait for an answer.
At least 0chatIdstringRequiredThe assistant conversation the run belongs to: the one that started it, or else the one its task was created in. Null when neither came from a conversation. The app shows the run in that conversation.
Can be nullcreatedAtstringRequiredWhen the run was queued.
Formatdate-timeupdatedAtstringRequiredWhen the run last changed: a step it took, an approval it started waiting for, or its end.
Formatdate-timestartedAtstringRequiredWhen a runner first picked it up.
Can be nullFormatdate-timefinishedAtstringRequiredWhen it ended.
Can be nullFormatdate-timetranscriptTaskRunStep[]RequiredThe record of the run in order: the instruction it started with, then every step it took with the tools that step called.
approvalsTaskApproval[]RequiredEvery approval request of the run, newest first.
TaskRunListobject
objectstring- One of
"list" dataTaskRun[]hasMorebooleanTrue when another page follows. Pass
nextCursorback ascursorto read it.nextCursorstringAn opaque cursor for the next page, or null on the last page. Pass it back unchanged.
Can be null
TaskRunStepobject
rolestringRequireduserfor the instruction the run started with,assistantfor each step it took.One of"user""assistant"textstringRequiredWhat was said at this step.
atstringRequiredWhen the step was taken.
Can be nullFormatdate-timecallsobject[]RequiredThe tools the step called.
idstringRequiredtoolstringRequiredThe tool, by the name the MCP server lists it under.
argsobjectRequiredWhat it was called with.
donebooleanRequiredFalse while the call waits for approval or has not run yet.
resultanyRequiredWhat the tool answered, or null until it has.
TaskTriggerobject
kindstringRequiredscheduleruns on a clock,mailruns when a message arrives, andmanualruns only when started by hand or through the API.One of"schedule""mail""manual"scheduleobjectWhen a
scheduletask runs. Needed for that kind and ignored for the others.Can be nullcadencestringRequiredhourlyruns everyeveryHourshours atminute,dailyruns athour:minuteon each ofweekdays, andmonthlyruns athour:minuteonmonthDay.One of"hourly""daily""monthly"everyHoursintegerFor
hourly: how many hours lie between runs, counted from midnight in the time zone.At least 1At most 12Default1hourintegerThe hour of the day, 0 to 23, in the time zone of the schedule.
At least 0At most 23Default8minuteintegerThe minute of the hour, 0 to 59.
At least 0At most 59Default0weekdaysinteger[]For
daily: the days it runs, 0 for Sunday to 6 for Saturday. Left out, it runs every day.1 to 7 itemsDefault[0,1,2,3,4,5,6]monthDayintegerFor
monthly: the day of the month, 1 to 28.At least 1At most 28Default1timezonestringAn IANA time zone such as
Europe/Berlin. The schedule follows its clock changes.1 to 64 charactersDefault"UTC"
mailobjectWhich arriving mail starts a
mailtask. Left out, every message that reaches an inbox does.Can be nulladdressesstring[]Start only for mail delivered to one of these addresses of the workspace. Empty means every address.
Up to 25 itemsDefault[]fromContainsstringStart only when the sender address contains this text, whatever the case.
Can be nullUp to 200 characterssubjectContainsstringStart only when the subject contains this text, whatever the case.
Can be nullUp to 200 characters