Rate limits & pagination

Limits apply to specific endpoints (sign-in, token creation, search, provisioning), not to the API as a whole. List endpoints page with page and limit, or offset and limit.

Rate-limited endpoints

These limits are enforced by the open-source API with fixed windows stored in Redis. Endpoints that are not listed have no per-endpoint limit in the API itself; your hosting (a proxy, LearnHouse Cloud's edge) may add its own.

ActionEndpointsLimitCounted per
Sign inPOST /auth/loginPOST /auth/magic-link/request30 per 5 minutesIP address
Refresh a sessionGET /auth/refresh600 per minuteIP address
Verify an emailPOST /auth/verify-email5 per 5 minutesemail address
Sign upPOST /users/POST /users/{org_id}POST /users/{org_id}/invite/{invite_code}10 per hourIP address
Accept an invite codePOST /users/{org_id}/invite/{invite_code}20 per 15 minutesIP address and organization
Password resetPOST /users/reset_password/…5 per 5 minutesemail address
Create or regenerate an API tokenPOST /orgs/{org_id}/api-tokensPOST /orgs/{org_id}/api-tokens/{token_uuid}/regenerate10 per hourIP address
Create or test a webhookPOST /orgs/{org_id}/webhooksPOST /orgs/{org_id}/webhooks/{webhook_uuid}/test20 per hourorganization, per action
SearchGET /search/org_slug/{org_slug}GET /folders/org/{org_id}/search60 per minuteuser (a token counts as its creator)
Provision a user (headless)POST /admin/{org_slug}/users30 per minuteAPI token
Look up a user by email (headless)GET /admin/{org_slug}/users/by-email/{email}60 per minuteAPI token
Send org invitesInvite endpoints under /orgs100 per dayorganization, and per inviting user

When you hit a limit

The API answers 429 Too Many Requests. How long to wait comes either as a Retry-After header (seconds) or, on the sign-in endpoints, as detail.retry_after next to the RATE_LIMITED code. Wait at least that long before trying again; retrying sooner does not reset the window.

429 responseJSON
{
  "detail": {
    "code": "RATE_LIMITED",
    "message": "Too many login attempts. Please try again in 4 minutes.",
    "retry_after": 263
  }
}

The SDK does not retry 429 for you: it retries only GET requests on network errors, timeouts and 5xx. Catch the LearnHouseError and check err.status === 429. See Errors.

Batch sizes

Endpoints that take a list of users or resources in one call (adding users to a group, adding course contributors, removing org members) accept at most 100 items per request; more returns 400 with code BATCH_TOO_LARGE and the cap in max_batch_size. Invites are capped at 25 emails per request.

Pagination

There are no cursors. Most list endpoints return a plain array; a few (search, org members, submissions) return an object, so check the endpoint's response schema. page starts at 1, offset at 0. With arrays, keep requesting the next page until you get fewer items than limit. Endpoints use one of three styles:

  • Path segments, …/page/{page}/limit/{limit} (6 endpoints).
  • Query parameters, ?page=1&limit=10 (7 endpoints). Where the schema sets a maximum, it is shown below.
  • Offset, ?offset=0&limit=20 (3 endpoints).
Paginate
# page 2, 20 courses per page
curl "https://api.learnhouse.io/api/v1/courses/org_slug/your-school/page/2/limit/20" \
  -H "Authorization: Bearer lh_YOUR_API_TOKEN"
EndpointStyleLimit
GET/users/{user_id}/coursespage / limit querymax 50, default 10
GET/orgs/{org_id}/userspage / limit querymax 100, default 20
GET/orgs/user/page/{page}/limit/{limit}page / limit in the pathmax 100
GET/orgs/user_admin/page/{page}/limit/{limit}page / limit in the pathmax 100
GET/admin/{org_slug}/courses/{course_uuid}/enrollmentspage / limit querymax 100, default 25
GET/admin/{org_slug}/usergroups/{usergroup_uuid}/memberspage / limit querymax 100, default 25
GET/courses/org_slug/{org_slug}/page/{page}/limit/{limit}page / limit in the path—
GET/courses/org_slug/{org_slug}/searchpage / limit querymax 50, default 10
GET/search/org_slug/{org_slug}page / limit querymax 50, default 10
GET/assignments/{assignment_uuid}/tasks/{assignment_task_uuid}/submissionsoffset / limit querymax 500, default 50
GET/assignments/{assignment_uuid}/submissionsoffset / limit querymax 500, default 50
GET/chapters/course/{course_id}/page/{page}/limit/{limit}page / limit in the path—
GET/activities/{activity_uuid}/versionsoffset / limit querymax 100, default 20
GET/folders/org/{org_id}/page/{page}/limit/{limit}page / limit in the path—
GET/media/org/{org_id}/page/{page}/limit/{limit}page / limit in the path—
GET/payments/{org_id}/accesspage / limit query—, default 25