Fetching Units

Fetching Units

Units in ManageBac are the curriculum planning documents that teachers build within each class. Each unit captures the scope of a period of teaching — including the central idea or statement of inquiry, key concepts, assessments, approaches to learning, and many other components depending on the programme. Teachers author units in the Unit Planner, and coordinators use them to map and review curriculum across the school.

The two unit endpoints make this data available via the API:

• GET /api/v2/units — returns a paginated list of all units for the school, with summary fields

• GET /api/v2/units/{id} — returns the full planning content for a single unit

Step 1: Fetch the list of units

The list endpoint returns all units for the school. By default, only active (non-archived) units are included. Like all list endpoints, the response is paginated and includes a meta object to help you loop through pages:

/api/v2/units?page=1

A typical response looks like this:

{
  "units": [
    {
      "id": 1234567,
      "title": "Where We Are in Place and Time",
      "description": "An inquiry into orientation in place and time...",
      "subject": { "id": 890, "name": "Homeroom" },
      "grade": "Grade 3",
      "grade_number": 3,
      "class_ids": [456789, 456790],
      "start_date": "2025-09-01",
      "end_date": "2025-10-31",
      "duration_in_weeks": 9,
      "archived": false,
      "created_at": "2024-06-15T10:22:00Z",
      "updated_at": "2025-08-01T08:44:00Z"
    },
    { ... }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 4,
    "total_count": 187,
    "per_page": 50
  }
}

Use meta.current_page and meta.total_pages to determine whether there are more pages to fetch. Continue incrementing the page parameter until current_page equals total_pages.

Note that each unit in the list includes a class_ids array. This tells you which classes the unit has been assigned to. A unit can appear in more than one class if it has been shared or duplicated across the school.

Step 2: Filtering the list

Three query parameters are available to narrow the results returned by the list endpoint.

By archived status

By default, archived units are excluded. To retrieve archived units instead, pass archived=true. To explicitly confirm you only want active units, pass archived=false. A unit's archived status in the API matches its archived state in the ManageBac Unit Planner.

Parameter passed	Active units returned	Archived units returned
(none)	✔️	❌
archived=false	✔️	❌
archived=true	❌	✔️

To retrieve all units regardless of archived status, you will need to make two separate requests — one for each state — and combine the results.

By class

To retrieve only units assigned to specific classes, pass one or more class IDs using the class_ids[] parameter:

/api/v2/units?class_ids[]=456789&class_ids[]=456790

This is useful when you already know which classes you are interested in and want to avoid fetching units for the entire school.

By last modified date

To retrieve only units that have been created or updated since a given point in time, pass a timestamp using modified_since:

/api/v2/units?modified_since=2025-09-01T00:00:00Z

This parameter is particularly useful for incremental sync — running a nightly or weekly fetch that only processes units that have changed since the last run, rather than pulling the full dataset every time.

Step 3: Fetch the full details of a unit

The list endpoint provides summary information. To retrieve the complete planning content of a unit — all the components a teacher has filled in — use the detail endpoint with the unit's id:

/api/v2/units/{id}

The response is wrapped in a unit key:

{
  "unit": {
    "id": 1234567,
    "title": "Where We Are in Place and Time",
    "central_idea": "People's connection to place shapes their identity and influences their decisions.",
    "key_concepts": {
      "key_concepts": [
        { "id": 11, "concept": "Connection" },
        { "id": 12, "concept": "Perspective" }
      ],
      "unit_key_concepts": [
        { "id": 501, "kind": "key", "explanation_related_concept": null }
      ]
    },
    "lines_of_inquiry": [
      { "id": 301, "line": "How places are connected through movement of people and ideas" },
      { "id": 302, "line": "The impact of migration on identity" }
    ],
    "formative_assessment": "<p>Exit tickets and discussion-based checks for understanding.</p>",
    "summative_assessment": "<p>Student-created map and reflective journal.</p>",
    "approaches_to_learning": {
      "atls": [
        { "id": 21, "name": "Research Skills", "children": [ ... ] }
      ],
      "atl_details": null
    },
    ...
  }
}

Coverage

The following tables describe what each field in the unit response represents in the ManageBac interface. Fields marked as detail only are not included in the list endpoint and require a separate request to /api/v2/units/{id}.

Always present

These fields are returned for every unit, in both the list and detail responses.

Field	What it represents
id	The unit's internal ManageBac ID
title	The unit name as displayed in the Unit Planner
description	The unit description
subject	The subject this unit belongs to, with ID and name
grade	The year level or grade name
grade_number	The numeric grade (useful for sorting)
class_ids	IDs of the classes this unit is assigned to
start_date / end_date	The planned start and end dates for the unit
duration_in_weeks	How many weeks the unit is planned to run
month / week	Scheduling placement within the academic year
hours	Planned teaching hours
sl / hl	Standard Level or Higher Level designation (DP)
language_level / language_b_phases	Language-specific fields (Language B)
idu_unit	Whether this is an Interdisciplinary Unit
archived	Whether the unit has been archived
created_at / updated_at	Timestamps for when the unit was created and last modified

Detail only — planning essentials

Field	What it represents
central_idea	The PYP Central Idea field
statement_of_inquiry	The MYP Statement of Inquiry
conceptual_understandings	Conceptual understandings text
key_concepts	IB Key Concepts selected for the unit, with explanations
related_concepts	Related Concepts, with subject and phase
specified_concepts	Specified Concepts (MYP Language and Literature)
lines_of_inquiry	Lines of Inquiry listed in the unit
guiding_questions	Guiding/inquiry questions, with their type labels and linked subjects
student_questions	Student-generated questions
teacher_questions	Teacher questions
transfer_goals	Transfer goals text
misunderstandings	Anticipated misunderstandings text
global_contexts	Selected Global Contexts with explorations and IDU subjects
transdisciplinary_theme	PYP Transdisciplinary Theme, with selected sub-options
contextual_lens	Contextual Lens selection

Detail only — assessment

Field	What it represents
formative_assessment	Formative assessment description (HTML)
summative_assessment	Summative assessment description (HTML)
peer_self_assessment	Peer and self-assessment description
ongoing_assessment	Ongoing assessment notes
student_self_assessment	Student self-assessment description
success_criteria	Success criteria text
standardization_and_moderation	Standardization and moderation notes
feedback	Feedback description
criteria	Assessment criteria, grouped by subject and level (HL/SL), in tree structure

Detail only — skills and approaches

Field	What it represents
approaches_to_learning	ATL skill categories and sub-skills selected for the unit, in tree structure
learner_profiles	Learner profile attributes selected for the unit
attitudes	Attitudes selected (PYP)
aims	Course aims, grouped by year and subject
objectives	Course objectives, grouped by year and subject
dispositions	Dispositions text

Detail only — content and context

Field	What it represents
content	Content text field
skills	Skills text field
learning_process	Learning process text
concepts	Concepts text
methods	Methods text
syllabus	Syllabus topics, in tree structure
scope_sequence	Scope and sequence expectations, by subject, phase/grade, and strand
standards	Aligned standards (Core Standards and external Standards), in tree structure
pedagogical_approaches	Selected pedagogical approaches and additional notes
unit_activities	Activities listed in the unit
prior_learning_experiences	Prior learning experiences text
student_expectations	Student expectations text
teaching_strategies	Teaching strategies text

Detail only — connections and resources

Field	What it represents
cross_curricular_links	Cross-curricular link options selected, with notes
co_curricular_links	Co-curricular link options selected, with notes
language_and_literacy_development	Language and literacy development options, with notes
differentiation	Differentiation options and notes
metacognition	Metacognition options and notes
support_materials	Support materials options and notes
international_mindedness	International mindedness text
community_engagement	Community engagement options selected, with principled action and learning process comments
information_communication_technology	ICT text field
academic_honesty / academic_integrity	Academic honesty or integrity text (field name varies by programme configuration)
agency	Agency text field
action	Action text field

Not all fields will be present in every unit response. Fields are only returned when the corresponding component is enabled for the unit's programme and school configuration. If a component is not enabled, its key will be absent from the response.

Practical notes

Combining list and detail calls

A common pattern is to use the list endpoint to collect all unit IDs across the school, then loop through those IDs to fetch the full detail for each unit. This allows you to control how much data you request and process it in batches.

Incremental sync

Use the modified_since filter on the list endpoint to avoid re-fetching units that have not changed. Store the timestamp of your last successful run, and pass it as modified_since on the next run. Because the list returns updated_at for each unit, you can also use this field to detect changes after the fact.

Programme variation

The fields present in a unit response depend on the programme the unit belongs to. A PYP unit will have central_idea, transdisciplinary_theme, and lines_of_inquiry, while an MYP unit will have statement_of_inquiry, global_contexts, and criteria. Do not assume a field will be present — always check whether the key exists in the response before attempting to read it.

HTML content

Several text fields — such as formative_assessment, summative_assessment, and central_idea — may contain HTML markup entered via ManageBac's rich text editor. If you are storing or displaying this content outside of ManageBac, plan for HTML parsing or stripping as appropriate.