A plan decides what a student may do: which kinds of lesson, how many each day, which languages. This guide covers how students and plans work, how a student’s plan is set and changed, and what your monthly statement counts.
Students
A student appears the first time your server launches them. We know a student only by your id for them (userId): never a name, phone number or email. Alongside it we keep only what you send or what their lessons produce:
- their plan, and the date it ends if you set one (
validTill); - up to four attributes for grouping:
cohort,batch,centreandplanCode; - the consent you recorded: when it was given (
dpdpConsentAt) and whether a guardian agreed (guardianConsent); - their status (active or paused), when they were first and last seen, and their lessons, questions and progress.
The console’s Students page finds a student by their id, or by a batch, centre, cohort, plan code or plan name. Search matches the exact text or its start, never the middle. Each student’s page shows what they have left today, their progress by folder, any refused starts, and every change made to them. Students launched with a sandbox key carry a Test student badge.
Plans in plain words
Your plans are set up with you by SketchMind, from your agreement: what each is called and how it is counted on your statement. In the API a plan is called an entitlement, and its API name (like school_plan) is on your console’s Plans page.
| A plan says | What a student meets when they reach it |
|---|---|
| Which kinds of lesson: library lessons, Ask lessons, or both | A launch of the other kind is refused mode_not_allowed. |
| Lessons per day | The next start is refused lessons_per_day. |
| Questions per day, asked during lessons | The question is refused doubts_per_day; the lesson carries on. |
| Trial lessons: a total for the student’s whole time with you, counting every lesson they have had on any plan | The next start is refused trial_exhausted. |
| Languages the student may learn in (empty means any we offer) | A launch in another language is refused language_not_entitled. |
Deepest depth for library lessons: quick, balanced or thorough | A deeper request plays the deepest one allowed. |
| Billed as, or Not billed | Set by SketchMind from your agreement; it names the statement line the student’s lessons count under. |
| Not counted (for your staff) | The student’s lessons stay out of every number. |
Your organisation also has:
- a default plan, used when a launch names no plan and the student has none yet;
- an expiry plan: when a student’s
validTilldate passes, they move to it (usually your default plan); - a fair-use question count for a month: we count how many students went over it, show that on your Overview and in the API’s statement, and tell your server with the
usage.alertwebhook. Nobody is stopped.
Every plan sits under a daily maximum per student that SketchMind sets for the whole platform; your Plans page shows it. Within a lesson, the tutor also limits how many questions it takes on one topic before moving on (topic_question_limit); the student can ask more after that topic.
Changing the plans themselves
Owners and admins edit plans on the Plans page. Each save, with the reason you give, lands in Activity.
- You can change the limits of your plans. A trial, a staff plan, or any plan that is not billed can only be kept or made tighter.
- Plans are added or removed by SketchMind: write to us.
- A change to question limits applies at once, even in a lesson that is running. A change to lesson limits applies from the next lesson.
How counting works
- A lesson counts when teaching starts: at the first step taught on the board, not at the launch. A student who opens a lesson and leaves before it starts uses nothing.
- A question counts when the tutor takes it on during a lesson. A question the tutor holds back (“let’s finish this topic first”) and a message like “thanks” count nothing.
- Days run on India time. Counts start again at midnight.
- What is left comes back on every launch as
caps.lessonsLeftTodayandcaps.doubtsLeftToday, and fromGET /v1/learners/{userId}. On a trial, lessons left today is never more than the trial has left.
When a student reaches a limit, they see a plain card in the player, never an offer to upgrade. Your page hears it as lumi.blocked, and your server as the session.blocked and learner.cap_reached webhooks. See Integration and Webhooks.
SketchMind sets a monthly limit for your organisation. If it is reached and the limit is set to pause, new lessons are refused with lessons_paused until the next month or until we raise it; lessons already running finish. The console says “New lessons are paused for your institution”, and the usage.alert webhook can warn you as it gets close.
Setting and changing a student’s plan
There are three ways to set a student’s plan:
| Way | How | What it sets |
|---|---|---|
| The launch | Name entitlement in POST /v1/launch. | The student’s plan, from this launch on. |
| The API | PATCH /v1/learners/{userId} with entitlement. | The same plan as the launch sets. Whichever of the two came last wins. |
| The console | Students › the student › set a plan here, with an optional end date. | A plan for this student only, which wins over the other two until its end date. |
The first two set what we call your app’s plan. A plan set in the console sits on top of it for a while (a scholarship, a make-up week), and when its end date passes, your app’s plan applies again. While it applies, the student’s lessons still count on your statement under your app’s plan. A console plan cannot be set while your app’s plan is a trial, a staff plan or another plan that is not billed; there your app’s plan always applies.
Reading a student tells you which plan is in force:
{
"userId": "stu_48213",
"entitlement": "school_plan",
"entitlementSetBy": "launch",
"planInForce": "school_plan_plus",
"planSetInConsole": true
}entitlementis your app’s plan, andentitlementSetBysays what last set it:launch,api,consoleorexpiry.planInForceis the plan that applies right now, andplanSetInConsoleis true when that is a plan set in the console.
A new plan applies from the student’s next lesson. Changing a plan does not start today’s counts again: a student who has used today’s lessons and moves to a plan that allows more gets the difference.
Pausing and erasing a student
- Pause a student with
PATCH /v1/learners/{userId}and"status": "suspended", or Pause access on the student’s page in the console. Their launches are refusedlearner_suspendeduntil you set"status": "active"again. - Erase a student with
DELETE /v1/learners/{userId}. It happens at once: their profile, ratings and progress are deleted, their lessons are kept only as anonymous records with no link to your id, and their attributes are cleared. Your id for them is held for 90 days, and a launch with it in that time is refusedlearner_suspended. The console shows them as Erased. Erasing is done through the API only.
curl -X DELETE "$LUMI_API/learners/stu_48213" \
-H "Authorization: Bearer $LUMI_KEY"The statement
Your statement counts your students’ lessons for each month, plan by plan, in the unit your agreement names. It counts; it never shows money.
| Your unit | What one unit is |
|---|---|
| Active students | A student who was taught at least once in the month. They count once, under the plan of their first lesson that month, moved up if a later lesson in the month was under a higher plan, never down. |
| Lessons | One lesson that reached teaching, split into library and Ask lessons. |
Every line also shows lessons started and completed, questions asked and minutes taught (lesson time up to the end of the lesson).
- Months run on India time. The current month is in progress; last month is settling until it becomes final on the 1st of the month after next; older months are final.
- Counted each night, so the statement reads to last night. A lesson taught an hour ago is on the Students page now and on the statement tomorrow.
- Left out: sandbox students (shown apart and never billed) and plans marked Not counted.
- Fair use: the API’s total row, and your Overview, show how many students went over your fair-use question count (the API also gives the most and the average per student).
Read it on the console’s Statements page (a month or a range, with CSV and print), or from your server:
curl "$LUMI_API/usage?from=2026-09&to=2026-10" \
-H "Authorization: Bearer $LUMI_KEY"The answer’s shape is in the API reference.