Todoist
Create, update, complete and move tasks in Todoist, read completed tasks, and manage projects, sections, comments, labels and reminders.
Connect Todoist
- In the sidebar, open Connections and press Add connection.
- Type
todoistand choose Todoist. - Choose Sign in with Todoist.
- Press Sign in with Todoist at the bottom of the sheet, then choose your account in Todoist’s window and allow access.
Or choose Paste your API token, paste it, and press Test and save. It stays until someone deletes it.
Sign in with Todoist, or paste your personal API token (Todoist → Settings → Integrations → Developer).
What if it says “Sign-in isn’t set up here yet”?
Signing in with Todoist needs a Todoist app on this installation, and it has none yet. Until it is set up, Paste your API token works without it.
On Cloud: The sheet says “It’s set up once for everyone who uses this service, not by an organization.”
Self-hosted: An admin of the installation sees Set up Todoist sign-in instead, and sets it up once for everyone. Everyone else sees who to ask.
- Create an app in Todoist’s developer settings (Todoist’s guide).
- In GoRunner, copy the Redirect address to add in Todoist’s developer settings, and add it to the app.
- Paste the Client ID and Client secret, then press Save and sign in.
Can I use my own Todoist app?
Yes. In the sheet, open Use your own Todoist app and paste its Client ID and Client secret. Add the redirect address it shows to your app first. The connection then signs in through your app instead of the installation’s.
Connections says how to sign in again, rename or delete it. In a product that embeds GoRunner, Add connection can be missing: then your provider makes connections for you.
Start a workflow
Add a trigger and choose Todoist. The trigger uses the same connection as the steps.
On New or Completed Task
Checks Todoist about once a minute and starts a run for each task added, or completed, since the check before, oldest first (at most 100 a minute; the rest follow). The first check after publishing only takes note of what is there (it starts nothing); changing the trigger starts over the same way. New task reads the active tasks (at most 2,000; pick a project for a bigger list), so a task added and completed between two checks is not seen; a task moved in from another project does not count as new. A recurring task fires each time it is completed.
- Trigger on · Required
What starts a run.
Options: New task, Task completed.
Default: New task.
- Project · Optional
Only tasks in this project. Empty watches every project.
A later step can use its data, such as {{trigger.added_at}}, {{trigger.change_type}}, {{trigger.completed_at}} and 9 more. See Use data from earlier steps.
Do things in Todoist
Add a Todoist step, choose a Resource, then an Operation. Choose a row to see its fields.
- TaskCreate · Quick Add · Get · Get Many · Get Completed · Update · Move · Close (complete) · Reopen · Delete
- ProjectCreate · Get · Get Many · Update · Archive · Unarchive · Get Collaborators · Delete
- SectionCreate · Get · Get Many · Update · Archive · Unarchive · Delete
- CommentCreate · Get · Get Many · Update · Delete
- LabelCreate · Get · Get Many · Update · Delete · Get Many Shared · Rename Shared · Remove Shared
- ReminderCreate · Get · Get Many · Update · Delete
Later steps read a step’s output by its name: see Use data from earlier steps.
Limits
- A reply from Todoist can be up to 16 MB (a file download can have its own limit). A larger one fails the step; it is never cut short.
- When Todoist says to slow down (429), the step waits as long as it asks, if the step’s time allows. Otherwise it fails and says when to try again.
Not in your list? See When an app isn’t here.
For developers
In the API, which calls apps pieces, Todoist is pieceId: "todoist" with actionId: "todoist", set by resource and an operation_… field, such as operation_comment. Its trigger is todoisttrigger / todoist_poll. Get an app returns every field.
It can change something outside the run (writes_external). See How versions and side effects work.
Todoist › Task
Create
- Content · Required
The task's title. Markdown links and formatting work as in the app.
- Description · Optional
Notes under the task's title.
- Project · Optional
The project. Empty is the Inbox on Create, and every project on Get Many and Get Completed.
- Section · Optional
A section of the project.
- Parent Task · Optional
The id or link of the task this one sits under (a subtask).
- Labels · Optional
Label names (such as launch, waiting). Todoist creates a personal label that does not exist yet. On Update the list replaces the task's labels.
- Priority · Optional
4 is the most urgent (shown as p1 in the app), 1 is normal (p4).
- Due (in words) · Optional
The due date as you would type it: tomorrow 5pm, every monday, Nov 7. On Update, "no date" removes it.
- Due Date · Optional
A due date without a time.
- Due Date and Time · Optional
A due date and time (ISO 8601). Give only one of the three due fields.
- Due Language · Optional
The language Due (in words) is written in: en, de, fr, es, … Empty is your Todoist language.
- Deadline · Optional
A deadline date, separate from the due date.
- Duration · Optional
How long the task takes, in Duration Unit. Needs a due date with a time when the unit is minutes.
- Duration Unit · Optional
Options: Minutes, Days.
Default: Minutes.
- Assignee · Optional
The user id of a collaborator in a shared project (Project › Get Collaborators lists them).
- Order · Optional
The task's position among its siblings (1 is first).
Quick Add
- Text · Required
The task as you would type it in Todoist's Quick Add, such as Send the launch note tomorrow 5pm #Work @launch p1.
- Comment · Optional
A comment to add to the new task.
- Reminder · Optional
When to be reminded, in words (such as tomorrow 9am).
- Default Reminder · Optional
Add your default reminder when the task has a due time.
Off by default.
Get, Close (complete), Reopen and Delete
- Task · Required
The task's id, or its link from the Todoist app.
Get Many
- Project · Optional
The project. Empty is the Inbox on Create, and every project on Get Many and Get Completed.
- Section · Optional
A section of the project.
- Parent Task · Optional
The id or link of the task this one sits under (a subtask).
- Label · Optional
Only tasks with this label.
- Task IDs · Optional
Only these tasks: ids separated by commas.
- Filter · Optional
A Todoist filter, such as today | overdue, or #Work & p1. When set, it replaces Project, Section, Parent Task, Label and Task IDs. It is used as written: to narrow by a value from an earlier step, use those fields instead.
- Filter Language · Optional
The language the Filter is written in. Empty is English.
- Return All · Optional
Read every task, page by page (at most 2000; past that the step fails rather than stop early).
Off by default.
- Limit · Optional
How many tasks to return (1–2000).
Default: 50.
Shows when Return All is off.
Get Completed
- Date Range Applies To · Optional
Options: When the task was completed (up to 3 months), When the task was due (up to 6 weeks).
Default: When the task was completed (up to 3 months).
- From · Required
The start of the range (ISO 8601 date and time).
- To · Required
The end of the range (ISO 8601 date and time).
- Project · Optional
The project. Empty is the Inbox on Create, and every project on Get Many and Get Completed.
- Section · Optional
A section of the project.
- Parent Task · Optional
The id or link of the task this one sits under (a subtask).
- Filter · Optional
A Todoist filter, such as today | overdue, or #Work & p1. When set, it replaces Project, Section, Parent Task, Label and Task IDs. It is used as written: to narrow by a value from an earlier step, use those fields instead.
- Filter Language · Optional
The language the Filter is written in. Empty is English.
- Return All · Optional
Read every task, page by page (at most 2000; past that the step fails rather than stop early).
Off by default.
- Limit · Optional
How many tasks to return (1–2000).
Default: 50.
Shows when Return All is off.
Update
- Task · Required
The task's id, or its link from the Todoist app.
- Content · Optional
A new title for the task. Empty keeps it.
- Description · Optional
Notes under the task's title.
- Labels · Optional
Label names (such as launch, waiting). Todoist creates a personal label that does not exist yet. On Update the list replaces the task's labels.
- Priority · Optional
4 is the most urgent (shown as p1 in the app), 1 is normal (p4).
- Due (in words) · Optional
The due date as you would type it: tomorrow 5pm, every monday, Nov 7. On Update, "no date" removes it.
- Due Date · Optional
A due date without a time.
- Due Date and Time · Optional
A due date and time (ISO 8601). Give only one of the three due fields.
- Due Language · Optional
The language Due (in words) is written in: en, de, fr, es, … Empty is your Todoist language.
- Deadline · Optional
A deadline date, separate from the due date.
- Duration · Optional
How long the task takes, in Duration Unit. Needs a due date with a time when the unit is minutes.
- Duration Unit · Optional
Options: Minutes, Days.
Default: Minutes.
- Assignee · Optional
The user id of a collaborator in a shared project (Project › Get Collaborators lists them).
- Order · Optional
The task's position among its siblings (1 is first).
Move
- Task · Required
The task's id, or its link from the Todoist app.
- Project · Optional
The project to move the task to. Give a Project, a Section or a Parent Task.
- Section · Optional
A section of the project.
- Parent Task · Optional
The id or link of the task this one sits under (a subtask).
Todoist › Project
Create
- Name · Required
The project's name.
- Parent Project · Optional
Create it inside this project.
- Color · Optional
Options: Berry red to Taupe (20 options).
- Favorite · Optional
Show it under Favorites in the sidebar.
- View · Optional
Options: List, Board, Calendar.
Get, Archive, Unarchive and Delete
- Project · Required
The project.
Get Many
- Archived Projects · Optional
List the archived projects instead of the active ones.
Off by default.
- Return All · Optional
Read every item, page by page (at most 2000; past that the step fails rather than stop early).
Off by default.
- Limit · Optional
How many items to return (1–2000).
Default: 50.
Shows when Return All is off.
Update
- Project · Required
The project.
- Name · Optional
A new name. Empty keeps it.
- Color · Optional
Options: Berry red to Taupe (20 options).
- Favorite · Optional
Show it under Favorites in the sidebar.
- View · Optional
Options: List, Board, Calendar.
Get Collaborators
- Project · Required
The project.
- Return All · Optional
Read every item, page by page (at most 2000; past that the step fails rather than stop early).
Off by default.
- Limit · Optional
How many items to return (1–2000).
Default: 50.
Shows when Return All is off.
Todoist › Section
Create
- Project · Required
The project to add the section to.
- Name · Required
The section's name.
- Order · Optional
The section's position in the project (1 is first).
Get, Archive, Unarchive and Delete
- Project · Optional
Only the sections of this project. Empty is every project.
- Section · Required
The section.
Get Many
- Project · Optional
Only the sections of this project. Empty is every project.
- Return All · Optional
Read every section, page by page (at most 2000; past that the step fails rather than stop early).
Off by default.
- Limit · Optional
How many sections to return (1–2000).
Default: 50.
Shows when Return All is off.
Update
- Project · Optional
Only the sections of this project. Empty is every project.
- Section · Required
The section.
- Name · Required
The section's name.
Todoist › Comment
Create
- Comment On · Optional
Options: A task, A project.
Default: A task.
- Task · Required
The task's id, or its link from the Todoist app.
Shows when Comment On is A task.
- Project · Required
The project.
Shows when Comment On is A project.
- Comment · Required
The comment's text (Markdown works as in the app; at most 15,000 characters).
- Attachment URL · Optional
A link to a file to attach to the comment.
- Attachment Name · Optional
The file's name as shown (such as agenda.pdf). Empty takes it from the URL.
- Attachment Type · Optional
The file's MIME type.
- Notify · Optional
User ids of collaborators to notify about the comment.
Get and Delete
- Comment · Required
The comment's id.
Get Many
- Comment On · Optional
Options: A task, A project.
Default: A task.
- Task · Required
The task's id, or its link from the Todoist app.
Shows when Comment On is A task.
- Project · Required
The project.
Shows when Comment On is A project.
- Return All · Optional
Read every comment, page by page (at most 2000; past that the step fails rather than stop early).
Off by default.
- Limit · Optional
How many comments to return (1–2000).
Default: 50.
Shows when Return All is off.
Update
- Comment · Required
The comment's id.
- Comment · Required
The comment's text (Markdown works as in the app; at most 15,000 characters).
Todoist › Label
Create
- Name · Required
The label's name (at most 128 characters).
- Color · Optional
Options: Berry red to Taupe (20 options).
- Order · Optional
The label's position in the list.
- Favorite · Optional
Show it under Favorites in the sidebar.
Get and Delete
- Label · Required
The personal label.
Get Many
- Return All · Optional
Read every label, page by page (at most 2000; past that the step fails rather than stop early).
Off by default.
- Limit · Optional
How many labels to return (1–2000).
Default: 50.
Shows when Return All is off.
Update
- Label · Required
The personal label.
- Name · Optional
A new name; tasks with the label keep it under the new name. Empty keeps it.
- Color · Optional
Options: Berry red to Taupe (20 options).
- Order · Optional
The label's position in the list.
- Favorite · Optional
Show it under Favorites in the sidebar.
Get Many Shared
- Leave Out Personal Labels · Optional
List only the labels used in shared projects, not your own labels of the same names.
Off by default.
- Return All · Optional
Read every label, page by page (at most 2000; past that the step fails rather than stop early).
Off by default.
- Limit · Optional
How many labels to return (1–2000).
Default: 50.
Shows when Return All is off.
Rename Shared
- Shared Label · Required
The shared label's name.
- New Name · Required
The name to give it on every task.
Remove Shared
- Shared Label · Required
The shared label's name.
Todoist › Reminder
Create
- Task · Required
The task to remind about: its id, or its link from the Todoist app.
- Type · Optional
On Update, the kind of time the new values set.
Options: Before the task is due, At a date and time.
Default: Before the task is due.
- Minutes Before · Optional
How many minutes before the task's due time to remind (the task needs a due time). 0 is at the due time.
Shows when Type is Before the task is due.
- Remind At · Optional
The date and time (ISO 8601). Without a time zone it is in Time Zone, or your own.
Shows when Type is At a date and time.
- Remind At (in words) · Optional
Or the moment in words, such as tomorrow at 9am. Give one of the two.
Shows when Type is At a date and time.
- Time Zone · Optional
An IANA time zone for Remind At.
Shows when Type is At a date and time.
- Send By · Optional
Empty uses your Todoist settings.
Options: Push notification, Email.
- Notify User · Optional
The user id of the collaborator to remind. Empty reminds you.
Get and Delete
- Reminder · Required
The reminder's id.
Get Many
- Task · Optional
Only this task's reminders. Empty lists every reminder.
- Return All · Optional
Read every reminder, page by page (at most 2000; past that the step fails rather than stop early).
Off by default.
- Limit · Optional
How many reminders to return (1–2000).
Default: 50.
Shows when Return All is off.
Update
- Reminder · Required
The reminder's id.
- Type · Optional
On Update, the kind of time the new values set.
Options: Before the task is due, At a date and time.
Default: Before the task is due.
- Minutes Before · Optional
How many minutes before the task's due time to remind (the task needs a due time). 0 is at the due time.
Shows when Type is Before the task is due.
- Remind At · Optional
The date and time (ISO 8601). Without a time zone it is in Time Zone, or your own.
Shows when Type is At a date and time.
- Remind At (in words) · Optional
Or the moment in words, such as tomorrow at 9am. Give one of the two.
Shows when Type is At a date and time.
- Time Zone · Optional
An IANA time zone for Remind At.
Shows when Type is At a date and time.
- Send By · Optional
Empty uses your Todoist settings.
Options: Push notification, Email.
- Notify User · Optional
The user id of the collaborator to remind. Empty reminds you.