Skip to main content
get_context (GET /v2/context) and suggest_day_plan (GET /v2/plan/suggestion) rank your open tasks with the same score. The rule is simple enough to reason about: lateness first, then how close the task is, then its priority.

​
What is ranked

Your own open tasks, calendar blocks (kind: "event") excluded. The score is computed for a reference day: the day argument, else your X-Doers-Today, else the current UTC day.

​
The score

A task’s date is the earlier of its planned date (when, when it is a date) and its deadline. Then, added to the above: A task planned for Wednesday, due Monday, two days late on Wednesday, priority 3, in a project: 100 + 2 × 3 + 40 + 6 = 152, with the reasons 2 days overdue and Priority P3. The reasons are English strings, ready to quote to a person.

​
The context

get_context returns, for the reference day:
  • counts: open tasks, overdue, due that day, and done in the last 7 days;
  • topPriorities: the highest-scoring open tasks (15 by default, up to 50 with limit), each with its score, reasons, when, deadline and project name;
  • your active projects with their open task counts, and your areas that are not archived.
It is the call to make first in a conversation.

​
The suggested plan

suggest_day_plan proposes a plan and writes nothing:
  1. it ranks your open tasks and keeps the best maxTasks (5 by default, 6 at most);
  2. it splits the working day, workStart to workEnd (09:00 to 18:00 by default), into rounds of roundMin minutes (120 by default);
  3. it deals the ranked tasks across the rounds in turn, so the most important work spreads over the day, at most 3 tasks per round;
  4. the first task becomes the suggested focus, focusTaskId.
Put the proposal to the person, then commit what they agree to with plan_today (PUT /v2/plan). A round’s own list is set with plan_round or set_round_plan.