> ## Documentation Index > Fetch the complete documentation index at: https://developers.primulamanagement.com/llms.txt > Use this file to discover all available pages before exploring further. # Get detailed spaces > The session must have schools assigned. Results are restricted to those schools; an optional school_id narrows this scope and must be assigned to the session. The selected representation determines accepted parameters; every unsupported parameter returns 400. | Representation | Selection | Required scope and dates | Additional parameters | | --- | --- | --- | --- | | Rows | Omit view/group_by/metrics | school_id, period | room_id, room_ids, fields, sort_by, page, per_page | | Aggregate | Omit view; set group_by and metrics | school_id, period | room_ids, sort_by, limit | | Trend | view=trend | school_id, room_id | period_from, period_to, fields | | Projection | view=projection | school_id | room_id, room_ids, period_from, period_to, fields | | Periods | view=periods | Session schools | school_ids, only_active | All modes accept company_id and view. Periods rejects school_id; use school_ids instead. Rows are paginated. Aggregate returns flat properties for the grouping key and metrics, with default limit 50 and cap 200. Trend, projection and periods are unpaginated. Omitting both range bounds uses the available calculated horizon. If filtering, both bounds must be present and within that horizon. An inverted range returns 400; a single bound or an out-of-horizon range fails in the data layer and currently returns 500. Projection always returns one row per room and period. Without a room filter it includes all rooms. The default projection fields omit room_id and room_name, so request those fields to distinguish rooms. fields differs between SpacesRow (rows/trend) and SpacesProjection. occupancy_rate is a ratio (0.8 means 80%). ## OpenAPI ````yaml /openapi.yaml get /spaces/detailed_list openapi: 3.1.0 info: title: Primula Tracker API V3 version: 3.0.0 description: >- Reference for the 66 operations registered under `/primula/api/v3` in the V3 release baseline. ## Authentication Create a session with `POST /sessions`, then send `Authorization: Bearer ` on protected operations. Tokens must remain associated with a valid server-side session. The returned refresh token has no refresh endpoint in V3. Session company and school restrictions are documented per operation; company_id is not inferred from the token. ## Responses and errors Collections generally return bare JSON arrays and items return bare JSON objects. Report objects, nested maps, and update summaries are explicitly described below. List metadata travels in response headers rather than an envelope. Empty lists written by collection helpers are `[]`; fields backed by nullable values may be `null`, and omitted properties are distinguished from null properties in schemas. Handlers generally return `{ "error": "message" }`; authentication middleware and activity proxy errors use plain text. Unsupported methods on a registered path return 405 with Allow after any applicable authentication checks. ## Pagination and projections Only operations documenting page/per_page support pagination. Defaults are page=1 and per_page=100. Values exceeding the documented effective cap are clamped, not rejected. X-Total-Count describes the full matching set. Link contains applicable navigation links and is omitted for a single page. Aggregates use limit (default 50, effective cap 200) instead of pagination and send X-Truncated only when rows were omitted. The fields parameter, where available, selects the exact response properties; unsupported fields return 400. ## Query encoding Multi-value parameters documented as arrays accept repeated keys or comma-separated values. Prefer repeated keys for long UUID lists. Except for the two activity proxy operations, query parsing drops the entire query string above 8192 bytes and truncates each decoded query value to 128 bytes. Parameter combinations and interpretation differ by resource and representation; consult each operation. Unknown parameters are rejected only where explicitly documented. ## Dates and writes Calendar dates use YYYY-MM-DD, monthly periods use YYYY-MM, and timestamp formats are described in the corresponding schema. Defaults such as today depend on the server clock. PATCH operations change only the documented properties and reject unknown body properties. Clearing values, authorization, and partial-write behavior vary by resource and are described per operation. Examples use synthetic identifiers and placeholder tokens. Replace the server host before using an interactive API client. servers: - url: https://{host}/primula/api/v3 description: V3 API deployment. Replace the placeholder hostname. variables: host: default: api.example.com security: - bearerAuth: [] tags: - name: sessions description: Sessions. - name: schools description: Schools. - name: companies description: Companies. - name: rooms description: Rooms. - name: users description: Users. - name: gusto_companies description: Gusto companies. - name: gusto_employees description: Gusto employees. - name: gusto_contractors description: Gusto contractors. - name: gusto_payrolls description: Gusto payrolls. - name: procare_staff description: Procare staff. - name: efficiency_ratios description: Efficiency ratios. - name: enrollment_tracker description: Enrollment tracker. - name: classroom_attendance description: Classroom attendance. - name: absences description: Absences. - name: billing_attendance_audits description: Billing attendance audits. - name: data_refresh description: Data refresh. - name: waitlist description: Waitlist. - name: sibling_discounts description: Sibling discounts. - name: new_start_tracker description: New start tracker. - name: withdrawal_tracker description: Withdrawal tracker. - name: transition_tracker description: Transition tracker. - name: enrollments description: Enrollments. - name: pre_registration_fallout description: Pre registration fallout. - name: procare_messages description: Procare messages. - name: activities_summary description: Activities summary. - name: activity_details description: Activity details. - name: leads description: Leads. - name: students description: Students. - name: payments description: Payments. - name: family_balances description: Family balances. - name: attendances description: Attendances. - name: billing_plans description: Billing plans. - name: spaces description: Spaces. paths: /spaces/detailed_list: get: tags: - spaces summary: Get detailed spaces description: >- The session must have schools assigned. Results are restricted to those schools; an optional school_id narrows this scope and must be assigned to the session. The selected representation determines accepted parameters; every unsupported parameter returns 400. | Representation | Selection | Required scope and dates | Additional parameters | | --- | --- | --- | --- | | Rows | Omit view/group_by/metrics | school_id, period | room_id, room_ids, fields, sort_by, page, per_page | | Aggregate | Omit view; set group_by and metrics | school_id, period | room_ids, sort_by, limit | | Trend | view=trend | school_id, room_id | period_from, period_to, fields | | Projection | view=projection | school_id | room_id, room_ids, period_from, period_to, fields | | Periods | view=periods | Session schools | school_ids, only_active | All modes accept company_id and view. Periods rejects school_id; use school_ids instead. Rows are paginated. Aggregate returns flat properties for the grouping key and metrics, with default limit 50 and cap 200. Trend, projection and periods are unpaginated. Omitting both range bounds uses the available calculated horizon. If filtering, both bounds must be present and within that horizon. An inverted range returns 400; a single bound or an out-of-horizon range fails in the data layer and currently returns 500. Projection always returns one row per room and period. Without a room filter it includes all rooms. The default projection fields omit room_id and room_name, so request those fields to distinguish rooms. fields differs between SpacesRow (rows/trend) and SpacesProjection. occupancy_rate is a ratio (0.8 means 80%). operationId: GetSpacesDetailedListV3 parameters: - $ref: '#/components/parameters/CompanyId' - name: school_id in: query required: false description: >- School UUID. Must be assigned to the authenticated session. Omit to use the operation's documented company/session scope. schema: type: string format: uuid example: 22222222-2222-4222-8222-222222222222 - name: view in: query required: false description: Omit for paginated rows or aggregation selected with group_by. schema: type: string enum: - trend - projection - periods - name: period in: query required: false description: Required for rows and aggregates; not accepted in the other views. schema: type: string pattern: ^\d{4}-(0[1-9]|1[0-2])$ - name: room_id in: query required: false description: >- Optional for rows/projection; required for trend; rejected for aggregates and periods. schema: type: string format: uuid - name: room_ids in: query required: false description: >- Optional for rows, aggregates and projection. Accepts repeated query parameters or comma-separated values; empty entries are dropped and surrounding whitespace is trimmed. schema: type: array items: type: string format: uuid style: form explode: true - name: school_ids in: query required: false description: >- Periods view only; each ID must be assigned to the session. Defaults to all assigned schools. Accepts repeated query parameters or comma-separated values; empty entries are dropped and surrounding whitespace is trimmed. schema: type: array items: type: string format: uuid style: form explode: true - name: only_active in: query required: false description: >- Periods view only: include only active schools. Accepts true/1 and false/0, case-insensitive. schema: type: boolean default: false - name: period_from in: query required: false description: >- Trend/projection only: optional first monthly period. Omit both bounds or provide both within the available horizon. schema: type: string pattern: ^\d{4}-(0[1-9]|1[0-2])$ - name: period_to in: query required: false description: >- Trend/projection only: optional last monthly period; must not precede period_from. Omit both bounds or provide both within the available horizon. schema: type: string pattern: ^\d{4}-(0[1-9]|1[0-2])$ - name: fields in: query required: false description: >- Select response properties. Unknown names return 400. Rows and trend use SpacesRow fields; projection uses SpacesProjection fields. Invalid fields for the selected view return 400. Accepts repeated query parameters or comma-separated values; empty entries are dropped and surrounding whitespace is trimmed. schema: type: array items: type: string enum: - available_spaces - capacity - closed_spaces - enrolled - is_over_enrolled - occupancy_rate - occupied_spaces - open_spaces - period - room_id - room_name - school_id - school_name - unavailable_spaces style: form explode: true - name: sort_by in: query required: false description: >- Rows: room_name, available_spaces, open_spaces, occupied_spaces or occupancy_rate with _asc/_desc. Aggregates: sum_available_spaces, sum_open_spaces, sum_occupied_spaces, sum_closed_spaces, sum_unavailable_spaces, capacity or occupancy_rate with _asc/_desc. Other views reject sort_by. Defaults: room_name_asc for rows; sum_open_spaces_desc for aggregates. schema: type: string - name: group_by in: query required: false description: Select an aggregate representation; metrics must also be supplied. schema: type: string enum: - room_id - room_name - school_id - school_name - name: metrics in: query required: false description: >- Metrics to calculate; required with group_by and invalid without it. Accepts repeated query parameters or comma-separated values; empty entries are dropped and surrounding whitespace is trimmed. schema: type: array items: type: string enum: - sum_available_spaces - sum_open_spaces - sum_occupied_spaces - sum_closed_spaces - sum_unavailable_spaces - capacity - occupancy_rate style: form explode: true - name: limit in: query required: false description: >- Aggregate result limit. Defaults to 50 and clamps values above 200 to 200. If provided, must be positive. schema: type: integer minimum: 1 default: 50 - name: page in: query required: false description: >- One-based page number. Rows only; other representations reject pagination parameters. schema: type: integer minimum: 1 default: 1 example: 1 - name: per_page in: query required: false description: >- Items per page; values greater than 200 are clamped to 200. Rows only; other representations reject pagination parameters. schema: type: integer minimum: 1 default: 100 example: 100 responses: '200': description: Successful response. content: application/json: schema: anyOf: - type: array items: $ref: '#/components/schemas/SpacesRow' - type: array items: $ref: '#/components/schemas/SpacesAggregate' - type: array items: $ref: '#/components/schemas/SpacesProjection' - type: array items: $ref: '#/components/schemas/SpacesPeriods' examples: rows: summary: Default row fields or trend view value: - school_id: 22222222-2222-4222-8222-222222222222 school_name: Example school room_id: 55555555-5555-4555-8555-555555555555 room_name: Example classroom period: 2026-01 capacity: 20 occupied_spaces: 16 available_spaces: 4 open_spaces: 3 closed_spaces: 1 unavailable_spaces: 0 occupancy_rate: 0.8 aggregate: summary: group_by=room_id&metrics=capacity,occupancy_rate value: - room_id: 55555555-5555-4555-8555-555555555555 capacity: 20 occupancy_rate: 0.8 projection: summary: >- view=projection&fields=room_id,period,enrolled,capacity,occupancy_rate value: - room_id: 55555555-5555-4555-8555-555555555555 period: 2026-01 enrolled: 16 capacity: 20 occupancy_rate: 0.8 periods: summary: view=periods value: - school_id: 22222222-2222-4222-8222-222222222222 school_name: Example school is_active: true room_count: 1 period_count: 1 periods: - 2026-01 period_start: 2026-01 period_end: 2026-01 headers: X-Total-Count: $ref: '#/components/headers/TotalCount' Link: $ref: '#/components/headers/Link' description: Only for the paginated row representation. X-Truncated: $ref: '#/components/headers/Truncated' description: Only for the aggregate representation. '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '405': $ref: '#/components/responses/405' '500': $ref: '#/components/responses/500' components: parameters: CompanyId: name: company_id in: query required: true description: >- Company UUID. Must equal the authenticated session company when that session has a company assigned; the equality check is skipped for sessions without one. schema: type: string format: uuid example: 11111111-1111-4111-8111-111111111111 schemas: SpacesRow: type: object description: >- A sparse row containing only the selected fields. Default fields: school_id, school_name, room_id, room_name, period, capacity, occupied_spaces, available_spaces, open_spaces, closed_spaces, unavailable_spaces, occupancy_rate. properties: school_id: type: string description: School id. school_name: type: string room_id: type: string description: Room id. room_name: type: string period: type: string pattern: ^\d{4}-(0[1-9]|1[0-2])$ capacity: type: integer occupied_spaces: type: integer available_spaces: type: integer open_spaces: type: integer closed_spaces: type: integer unavailable_spaces: type: integer occupancy_rate: type: number description: >- Occupied spaces divided by capacity; ratio, not a percentage. Zero when capacity is zero. is_over_enrolled: type: boolean additionalProperties: false SpacesAggregate: type: object properties: room_id: type: string description: >- Grouping value; missing data may be represented by an empty or unknown label. room_name: type: string description: >- Grouping value; missing data may be represented by an empty or unknown label. school_id: type: string description: >- Grouping value; missing data may be represented by an empty or unknown label. school_name: type: string description: >- Grouping value; missing data may be represented by an empty or unknown label. sum_available_spaces: type: integer sum_open_spaces: type: integer sum_occupied_spaces: type: integer sum_closed_spaces: type: integer sum_unavailable_spaces: type: integer capacity: type: integer occupancy_rate: type: number description: >- Occupied spaces divided by capacity; ratio, not a percentage. Zero when capacity is zero. additionalProperties: false description: >- Contains the selected grouping key and requested metrics only. Grouping and metrics are flat properties on this resource. SpacesProjection: type: object description: >- A sparse row containing only the selected fields. Default fields: school_id, school_name, period, enrolled, capacity, occupancy_rate. properties: school_id: type: string description: School id. school_name: type: string room_id: type: string description: Room id. room_name: type: string period: type: string pattern: ^\d{4}-(0[1-9]|1[0-2])$ enrolled: type: integer capacity: type: integer occupancy_rate: type: number description: >- Occupied spaces divided by capacity; ratio, not a percentage. Zero when capacity is zero. additionalProperties: false SpacesPeriods: type: object properties: school_id: type: string description: School id. school_name: type: string is_active: type: boolean room_count: type: integer period_count: type: integer periods: type: - array - 'null' items: type: string period_start: type: string period_end: type: string required: - school_id - school_name - is_active - room_count - period_count - periods description: Spaces Periods. Error: type: object properties: error: type: string description: Human-readable error message. required: - error description: Error. headers: TotalCount: description: >- Total matching rows before pagination, or matching groups before the aggregate limit. For unpaginated arrays, the number of returned rows. schema: type: integer minimum: 0 example: 125 Link: description: >- Pagination links using rel="next", "last", "prev", and "first". Only applicable links are sent; absent when all results fit on one page. Links preserve the original query parameters. schema: type: string example: >- ; rel="next" Truncated: description: Present with value true only when an aggregate result exceeds its limit. schema: type: boolean example: true responses: '400': description: Invalid or missing parameters or request body. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Invalid or missing parameters or request body. '401': description: >- Missing or invalid Bearer token, or an absent, invalid or expired server-side session. The authentication middleware returns plain text with a trailing newline. content: text/plain: schema: type: string examples: missing: value: | missing authorization header invalid: value: | Unauthorized expired: value: | Session expired '403': description: The authenticated session is not allowed to perform this operation. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: >- The authenticated session is not allowed to perform this operation. '405': description: The path exists but does not support this HTTP method. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: The path exists but does not support this HTTP method. headers: Allow: description: Comma-separated HTTP methods accepted by this path. schema: type: string '500': description: The operation could not be completed. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: The operation could not be completed. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Access token issued by POST /sessions and associated with a valid server-side session. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.