> For the complete documentation index, see [llms.txt](https://guide.fariaedu.com/integrations-portal/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guide.fariaedu.com/integrations-portal/managebac/recipes/fetching-units.md). # 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: ```json { "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: ```json { "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": "

Exit tickets and discussion-based checks for understanding.

", "summative_assessment": "

Student-created map and reflective journal.

", "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.