ielts-practice

IELTS Buddy Practice Interfaces

This Skill only describes the catalog and read-only record interfaces related to browser practice. Before calling personal data, first followAgent API Configurationto bind and check capabilities.

Interfaces

Capability	Data or Action	Call Constraints
ielts_prediction_search_hits	Public exam room records and possibly corresponding questions	Token may not be required; retain source and recall information, and only use the candidate questions and optional practice entry points returned by the server.
ielts_practice_list_taxonomy、ielts_practice_search_parts、ielts_practice_read_part	Question bank categories, catalog, and non-answer content	Do not reproduce complete test questions in chat.
ielts_dictation_search_materials	Catalog of listening materials for sentence-by-sentence intensive listening and contentRef	Only return material facts; do not create intensive listening runs or browser entry points.
ielts_practice_recent_activity、ielts_practice_read_session	Current account session status	Only read data for the current account.
ielts_review_read_snapshot	Answers, answer keys, and optional materials for submitted sessions	The server does not provide error causes, evidence, or teaching conclusions.

python3 scripts/ielts_buddy_api.py capabilities
python3 scripts/ielts_buddy_api.py call ielts_practice_search_parts --json '{"subject":"reading","limit":1}'

Boundaries

• A prediction hit result consists of two layers: the "exam room record" and candidates .source、title、recallContent, date, and test center belong to the source record and cannot be merged with candidate questions into the same fact.
• candidates are possibly corresponding questions,matchScore only indicates a match value and does not mean the source platform confirms a hit. When displaying, retain all candidates returned by the server, not just the first item, and do not set a second-layer threshold on your own.
• The candidate question's practiceUrl is optional; only provide a practice entry point when it is non-empty. The absence of a practice entry point does not affect the validity of the exam room record or the candidate question itself.
• Exam room records older than three months can still be queried, but the server no longer performs question bank matching for them; returning an empty candidates is a normal result.
• Token is only used for data interfaces; browser web login state is only used for practice pages, and the two cannot be interchanged.
• The Agent does not create, fill in, or submit formal practice; the user manually starts, answers, and submits in the browser practice center, and the Agent reads authoritative records after completion.
• Question bank sources only use search_parts returned origin.questionBank、origin.sourceBook、origin.sourceTest and origin.sourceUnit; do not infer sources from titles or ordinary tags.
• This Skill does not define question selection, diagnosis, review, or study plans.
• workflows/ is an independent optional recommendation layer and is not part of this Skill's interface contract.

List and Details

Querying study records has two steps: first read the list summary, then as needed use the returned reviewTarget to call ielts_review_read_snapshot to view the details of a practice session or a completed mock exam subject; for intensive listening use attemptId to call ielts_dictation_read_attempt, and for unsubmitted ordinary practice use sessionId to call ielts_practice_read_session. Do not expand details one by one just to list records. Before use, rely on the current account's capabilities.

In the list, sessionId is the number of practice attempts,partId is distinct passages; distinguish zero answers, answered but unsubmitted, and submitted, and do not infer IELTS scores from the accuracy of partial questions. When complete records are needed, paginate by nextOffset、nextCursor or nextPage until hasMore=false; when an empty page has a subsequent cursor, you still need to continue.observationTruncated=true or coverage.sourceTruncated=true indicates the data is still incomplete, and you must not claim it is fully retrieved. The plan list contains only summaries; use planId to call ielts_study_plans_get to get the task page.

Footprint and learning statistics

Cross-product activity uses ielts_footprints_list. Directly reading the server-side summary、dailyCounts、todayCounts and total；activities is only this page; its length or date distribution cannot be used to recalculate historical totals, heatmaps, streaks, or this week's counts. When only querying statistics, there is no need to pull the entire timeline.

Footprint preferentially uses nextCursor as-is as the cursorof the next request, keeping kinds/query/timeRange unchanged. The statistics scope is statisticsScope=filtered_history, the time zone is Asia/Shanghai, and the daily counts cover the 28 days up to the day of asOf . Video progress for the same chapter and same day is collapsed into one display activity, while the original events are retained.

ielts_learning_pull_events synchronizes raw learning evidence; the numeric cursor and the footprint's string cursor are not interchangeable, and their item counts should not be directly compared either. When the webpage does not display records, first verify pagination and coverage scope, and do not use ielts_learning_push_events to backfill facts that already exist. When missing fields or coverage.sourceTruncated=true are returned, maintain the conclusion of "incomplete," based on the currently deployedfootprint API documentation.