What is the difference between the Upcoming and Future buckets when using the API to list assignments?

[AndrewMerrill]

When using the API to List Assignments (https://canvas.instructure.com/doc/api/assignments.html#method.assignments_api.index), the bucket parameter can take several different values, including upcoming and future.  What is the difference between upcoming and future?  There doesn't appear to be a description of either on the documentation page.

Thanks for your help!

[Gabriel33 · Accepted solution]

From testing on my instance:

• upcoming is when a quiz is already available (but before the due date)
• future is when it is before the quiz availability date

[Gabriel33 · Accepted solution]

From testing on my instance:

• upcoming is when a quiz is already available (but before the due date)
• future is when it is before the quiz availability date

[dbrace · Accepted solution]

Hi @AndrewMerrill,

I did not know the answer to this question, so I turned to ChatGPT and used the following prompt.

When using the Canvas API for listing assignments, there is a parameter named bucket that has the following allowed values: past, overdue, undated, ungraded, unsubmitted, upcoming, future. May I please get a description and example for each of the allowed values.

Below is the response that I received:

When using the Canvas API to list assignments, the bucket parameter allows you to filter assignments based on their status or date relative to the current time. Below are the descriptions of the allowed values for bucket, along with examples of how they work:

1. past
   • Description: This bucket includes assignments that have already passed their due date, regardless of whether they were submitted or graded.
   • Example: If today is April 16, 2025, and the due date of an assignment was April 10, 2025, it would appear in the "past" bucket.
2. overdue
   • Description: This bucket includes assignments that are past their due date but have not been submitted yet. It’s essentially a subset of "past" that filters only the unsubmitted assignments.
   • Example: If today is April 16, 2025, and an assignment was due on April 10, 2025, but the student has not yet submitted it, it would appear in the "overdue" bucket.
3. undated
   • Description: This bucket includes assignments that do not have a due date set. These assignments might still be assigned to students but have no specific deadline.
   • Example: An instructor may create an assignment with no set due date, and it would show up in the "undated" bucket. For instance, a research project or a task that needs to be done at any time.
4. ungraded
   • Description: This bucket includes assignments that have been submitted but not yet graded.
   • Example: If a student submits an assignment on time, but the instructor has not yet graded it, that assignment would appear in the "ungraded" bucket.
5. unsubmitted
   • Description: This bucket includes assignments that have been assigned to students but have not yet been submitted. It is similar to the "overdue" bucket, but it does not necessarily mean the assignment is past due—it just hasn’t been submitted.
   • Example: A student was assigned a project due on April 20, 2025, and has not yet submitted it by April 16, 2025. This assignment would appear in the "unsubmitted" bucket.
6. upcoming
   • Description: This bucket includes assignments that are due in the future (i.e., after the current date).
   • Example: If today is April 16, 2025, and an assignment is due on April 30, 2025, it would appear in the "upcoming" bucket.
7. future
   • Description: This bucket includes assignments that have a future due date but may not yet be visible to students (in cases where visibility settings prevent students from seeing assignments before a certain date). It’s like the "upcoming" bucket, but may include assignments that are not yet "released" to students.
   • Example: If today is April 16, 2025, and an assignment is due on May 10, 2025, but the instructor has set it to be visible starting May 1, 2025, the assignment would show up in the "future" bucket.

Maybe you could use beta or a sandbox course to try and duplicate the possiblities

Since I used ChatGPT for help, I cannot vouch for the accuracy of the response but I hope that you find it helpful.

-Doug