Skip to main content

​
Pagination

Every list method returns a cursor envelope: 
{
  "data": [ /* up to `limit` records */ ],
  "has_more": true,
  "next_cursor": "crs_01HX9..."
}
The default limit is 20. The maximum is 100. 
let cursor: string | undefined;
do {
  const page = await hk.courses.list({ limit: 100, starting_after: cursor });
  for (const c of page.data) console.log(c.id);
  cursor = page.has_more ? page.next_cursor : undefined;
} while (cursor);

$cursor = null;
do {
    $page = $hk->courses->list(['limit' => 100, 'starting_after' => $cursor]);
    foreach ($page->data as $c) {
        echo $c->id . "\n";
    }
    $cursor = $page->has_more ? $page->next_cursor : null;
} while ($cursor);
For ergonomics, all list methods are also iterable — the iterator transparently fetches the next page when you reach the end of the current one. 
for await (const course of hk.courses.list({ limit: 100 })) {
  console.log(course.id);
}

foreach ($hk->courses->list(['limit' => 100])->autoPagingIterator() as $course) {
    echo $course->id . "\n";
}
Most retrieval methods accept expand to inline related resources in the same response, à la SQL JOIN. This avoids the N+1 problem. 
const course = await hk.courses.retrieve("crs_123", {
  expand: ["cohorts", "cohorts.lessons", "cohorts.lessons.activities"],
});

// course.cohorts[0].lessons[0].activities[0] is a fully-hydrated Activity

$course = $hk->courses->retrieve('crs_123', [
    'expand' => ['cohorts', 'cohorts.lessons', 'cohorts.lessons.activities'],
]);

// $course->cohorts[0]->lessons[0]->activities[0] is a fully-hydrated Activity
You can expand up to 3 levels deep, and up to 5 paths per call. Expanding past the limit returns 400 invalid_request_error with code: "expand_too_deep".

​
What’s expandable on each resource

ResourceExpandable paths
Coursecohorts, cohorts.units, cohorts.lessons, cohorts.lessons.activities
Cohortcourse, units, lessons, students, teachers
Unitlessons, lessons.activities
Lessonunit, activities, content, assignment
Activityquestions, lesson
Assignmentlesson, submissions
Submissionassignment, student
Usercohorts, courses
Anything not in this table is fetched lazily — i.e. you’ll need a separate retrieval call.

​
Filtering on lists

List methods accept resource-specific filters as parameters: 
hk.cohorts.list({ course_id: "crs_123", status: "active" });
hk.lessons.list({ cohort_id: "coh_123", type: "video" });
hk.submissions.list({ assignment_id: "asg_123", student_id: "usr_123" });

$hk->cohorts->list(['course_id' => 'crs_123', 'status' => 'active']);
$hk->lessons->list(['cohort_id' => 'coh_123', 'type' => 'video']);
$hk->submissions->list(['assignment_id' => 'asg_123', 'student_id' => 'usr_123']);
Refer to each list method’s API reference for the exhaustive list.