Class percentile rank of a score
A score of 85 in a class of 10 where 5 scored lower, 2 tied and 3 scored higher ranks at the 50th percentile. Paste the class marks and one score to see the share of classmates below it, plus the share at or below. Free in your browser.
- Free
- Runs in your browser
- No sign-up
- Your data stays on your device
Run — free
Worked example
- Score
- 85
- N
- 10
- Below
- 5
- Equal
- 2
- Above
- 3
A class percentile rank answers a question every gradebook eventually asks: given this student's score, what share of the class scored lower? Teachers, counselors, LMS authors, and parents do not want a k-th percentile cutoff or a verbal band; they want a rank computed from the actual roster sitting in front of them. Spreadsheet recipes drift between exclusive, inclusive, and midrank formulas, and two sections of the same course can report different ranks for the same mark when the comparison list is not pinned down. This calculator takes one query score and a finite list of class scores, counts how many roster marks fall strictly below the query, and returns that count as a percentage of class size. No network, no model, and no randomness: you supply the roster and the score, and the rank is reproducible for every valid input.
How a class percentile rank is defined from a roster
Class percentile rank is not the same statistic as the k-th percentile of a data set. The k-th percentile answers what score sits at a chosen position on an ordered list; class percentile rank answers the inverse classroom question: of the marks already on the roster, what percentage sit strictly below this student's score.
The exclusive formula used here is PR equals B over N times one hundred, where N is the length of the scores list you send and B is the count of roster values that are strictly less than the query score.
Ties do not inflate the exclusive rank: classmates who match the query count in equal, not in below, so a unique top mark in a class of ten has B equals nine and a rank of ninety, while a score that four classmates also earned still reports only the share who scored lower. The response also reports percent at or below, which is B plus E over N times one hundred, because report cards sometimes need that inclusive companion as well.
This is not the midrank convention that gives half credit for ties, and it is not a z-score or a letter on a bell curve; those tools start from a mean and a standard deviation rather than from a concrete list. You decide whether the roster includes the query student. If the list is the full class including that student, N is the class size and a self-match appears in equal.
If the list is everyone else, N is the number of classmates and the rank is the share of peers who scored lower. Either reading is valid; the calculator does not insert or drop the query score on its own. Boundary cases are honest: the lowest unique mark yields a rank of zero, a score above every roster mark yields one hundred, and a class of one with a matching score yields zero exclusive rank and one hundred percent at or below.
The engine never estimates a mean, never interpolates between order statistics, and never maps the rank onto low, average, or high bands. It counts, divides, and returns the two percentages plus the below, equal, and above tallies so a teacher can show the arithmetic on a whiteboard.
Where a class percentile rank earns its keep
Classroom gradebooks and LMS plugins need one documented mapping from a raw mark plus a roster to a 0–100 rank so the printed report, the parent portal, and the office-hours explanation never contradict each other on the same student. Department chairs who compare sections want the exclusive share-who-scored-lower figure rather than each instructor inventing a different tie rule in a personal spreadsheet.
Ed-tech products that already store item scores can attach a class percentile at the edge without shipping a second statistics engine or uploading a roster to a third-party site. Content sites that rank for class percentile rank or percentile rank of a score queries benefit from a free in-browser path that matches the paid automation path byte-for-byte on the same analytic library. Failed validation does not consume balance.
What you can do with it
Gradebook rank on a posted roster
Turn one student mark plus the section score list into the exclusive percentile rank for the report card and the LMS.
Office-hours and parent explanations
Show below, equal, and above counts so a family can see how many classmates scored lower than a given mark.
FAQ
Does a tie raise the percentile rank?
No. Classmates who match the query count in equal, not in below.
Should the student's own score be in the scores list?
Either way is valid. If the roster includes that student, n is the class size and a self-match appears in equal. If the list is everyone else, n is the number of classmates. The calculator does not insert or drop the query score.
Is this the same as a k-th percentile or a midrank percentile rank?
No. A k-th percentile finds a cutoff value on a sorted list. Midrank gives half credit for ties. This tool reports the exclusive classroom share who scored strictly lower.
What is the difference between percentile rank and percent at or below?
The percentile rank counts only the marks strictly lower than the score, while the second figure adds the ties. In the example, 5 of 10 scored lower, giving 50, and with the 2 tied marks it becomes 70.
Do I need the class mean and standard deviation?
No. The rank comes straight from the list of marks you paste, so no average, spread or bell curve is assumed. That makes it a direct answer for a real roster rather than an estimate from a z-score.
Related tools
For developers — API access
Everything on this page is available programmatically. This section is for teams who want to wire it into their own systems; everyone else can just use the tool above.
API endpoint
Prefer to automate it? One authenticated POST creates the task; the result comes back by webhook or a signed link. The same capability also runs here on the web, by email and from Telegram — and soon from our app too.
Call it from your stack
curl -X POST https://api.kit.forhosting.com/edu/percentile-rank-class \
-H "Authorization: Bearer $KIT_KEY" \
-H "Content-Type: application/json" \
-d '{"score":85,"scores":[62,71,74,78,81,85,85,88,92,97]}'const res = await fetch("https://api.kit.forhosting.com/edu/percentile-rank-class", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.KIT_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"score": 85,
"scores": [
62,
71,
74,
78,
81,
85,
85,
88,
92,
97
]
})
});
const { task_id } = await res.json();import os, requests
res = requests.post(
"https://api.kit.forhosting.com/edu/percentile-rank-class",
headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
json={
"score": 85,
"scores": [
62,
71,
74,
78,
81,
85,
85,
88,
92,
97
]
},
)
task_id = res.json()["task_id"]<?php
$res = file_get_contents("https://api.kit.forhosting.com/edu/percentile-rank-class", false, stream_context_create([
"http" => [
"method" => "POST",
"header" => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
"content" => '{"score":85,"scores":[62,71,74,78,81,85,85,88,92,97]}',
],
]));
$task = json_decode($res, true);body := bytes.NewBufferString(`{"score":85,"scores":[62,71,74,78,81,85,85,88,92,97]}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/edu/percentile-rank-class", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)Example request
{
"score": 85,
"scores": [
62,
71,
74,
78,
81,
85,
85,
88,
92,
97
]
}Example response
{
"task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
"type": "edu.percentile_rank_class",
"status": "queued",
"_links": {
"result": "/tasks/tsk_…/result"
}
}The API is asynchronous: the call returns a task_id immediately and the result arrives by webhook. Polling is capped at 1 req/s per task.
Pricing
Published price — no tokens, no invented credits. A failed task is never charged.
Limits
max_n | 10000 |
max_abs | 1000000000000000 |
Errors
| HTTP | Code | Meaning |
|---|---|---|
401 | unauthorized | Missing or invalid API key. |
402 | insufficient_balance | Your balance doesn't cover the task price. |
404 | unknown_type | That task type doesn't exist. |
429 | rate_limited | Too many requests. Use the webhook instead of polling. |
Technical notes
The same deterministic module powers the free browser tool and the API path, so a gradebook plugin and an office-hours check never disagree.
Input contract, response fields, and validation
Example: score seventy-five against fifty, sixty, seventy, eighty, ninety — a query that is not itself on the list — yields below three, equal zero, above two, and a rank of sixty. POST a JSON body with two required fields: score, a finite number on the same scale as the roster, and scores, a non-empty list of finite class marks. score accepts the aliases value, mark, raw, and x. scores accepts class_scores, roster, data, and values, and a comma-separated or whitespace-separated string of numbers is also accepted when a form posts plain text instead of a JSON array. Each element is parsed as a finite decimal; optional leading signs and scientific notation are allowed, while empty tokens, booleans, objects, Infinity, and NaN fail with invalid_input so a bad cell never becomes a silent zero. The engine enforces a hard maximum of ten thousand roster marks and a per-value magnitude ceiling so memory and latency stay inside a predictable budget on the free browser path and on the Worker. Missing score, missing scores, an empty list, or a list that exceeds the published length fail with invalid_input and are not billed. On success the body echoes score, returns n as the roster length, below, equal, and above as the three-way split of that roster, percentile_rank as one hundred times below over n, percent_at_or_below as one hundred times below plus equal over n, class_min and class_max as the observed ends of the list, method as exclusive_below, a short formula string, the published max_n ceiling, and a one-line message for UI copy. Example: score 85 against the ten-mark roster sixty-two, seventy-one, seventy-four, seventy-eight, eighty-one, eighty-five, eighty-five, eighty-eight, ninety-two, ninety-seven yields below five, equal two, above three, percentile_rank fifty, and percent_at_or_below seventy. Optional fields are omitted rather than null, and all names are DOM-safe snake_case for widgets and SDKs.
Where a class percentile rank earns its keep
Tutoring centers and academic-success offices explain to families why an eighty-two sits near the middle of a hard exam and near the bottom of an easy one; a deterministic API lets those conversations start from the same counts. Keep payloads tiny, pin percentile_rank together with below and n in tests, and you get reproducible classroom ranks for gradebook plugins, registrar scripts, and parent reports without standing up a full psychometrics stack of your own. Pair this endpoint with a band classifier if you later want a verbal label, and with a separate k-th percentile tool if you need a cutoff value rather than a rank of one score.
Integration use cases
LMS and registrar automation
Attach a machine-stable percentile_rank to stored class rosters using the same exclusive formula as the free browser tool.
Technical questions
How is class percentile rank computed?
Send score and the class scores list. The API counts roster marks strictly below the score, divides by n, and multiplies by 100. That exclusive share is percentile_rank.
What does the class percentile rank calculator cost?
The browser tool is free. API requests use prepaid KIT balance at $0.002 per successful call; invalid input is not billed.