> ## Documentation index > Fetch the complete documentation index at: https://developer.rhombus.com/llms.txt > Use it to discover all available pages before exploring further. # Get occupancy counts > Returns the estimated occupancy count for a specified room or area within a given time range. This endpoint allows you to monitor occupancy trends over time or retrieve a single count for a defined interval. > Important: An occupancy region must be defined in the Rhombus Console before using this endpoint. > You can optionally specify an interval (e.g., MINUTELY, QUARTERHOURLY, HOURLY ...) to retrieve occupancy counts broken down by sub-intervals between startTime and endTime. > If no interval is provided, a single occupancy count is returned for the entire duration between startTime and endTime. ```http POST https://api2.rhombussystems.com/api/report/getOccupancyCounts ``` EU organizations send the same request to `https://api2.eu.rhombussystems.com`. ## Authentication and parameters - `x-auth-apikey` (header, required): Your Rhombus API key. Must be accompanied by the `x-auth-scheme` header set to `api-token` (or `partner-api-token` for partner endpoints). - `Authorization` (header): instead of an API key, an OAuth access token (`Bearer `) with the `read` scope. - `x-auth-scheme` (header, string, default: `api-token`): Authentication scheme identifier. Use `api-token` or `partner-api-token` with the `x-auth-apikey` header, `api` or `partner-api` with `x-auth-apikey` plus a client certificate, `api-oauth-token` or `partner-api-oauth-token` with `x-auth-access-token`, and `federated-token` with `x-auth-ft`. A request with `Authorization: Bearer ` and no `x-auth-scheme` is treated as OAuth, and `federated-token` may also be sent as the `x-auth-scheme` and `x-auth-ft` query parameters. One of: `api-token`, `api`, `api-oauth-token`, `federated-token`, `partner-api-token`, `partner-api`, `partner-api-oauth-token`. - `x-auth-org` (header, string): Client organization UUID (22-character RUUID), for partner credentials only. With it the call runs in that client organization with the partner support authority's role. Without it a partner credential runs as the partner organization, which outside the partner endpoints is deprecated (responses carry `Deprecation` and `Sunset: Tue, 05 Jan 2027 00:00:00 GMT`). A malformed value returns 400 `INVALID_AUTH_ORG`; a client organization the partner cannot access returns 403 `PARTNER_CLIENT_ACCESS_DENIED`. ## Request body Content type: `application/json`. Request object for getting occupancy counts from a device. - `deviceUuid` (string | null): RUUID with optional appended facet information - `endTimeMs` (integer | null): The end timestamp (in Unix epoch milliseconds) of the selected interval - `interval` (string): Report interval for filtering face events One of: `MINUTELY`, `QUARTERHOURLY`, `HOURLY`, `DAILY`, `WEEKLY`, `MONTHLY`. - `startTimeMs` (integer | null): The start timestamp (in Unix epoch milliseconds) of the selected interval ## Response 200 OK. Content type: `application/json` - `error` (boolean | null) - `errorCode` (string | null): Stable, machine-readable code for the failure (one of the ApiErrorCode catalog) when error is true. Branch on this, not on errorMsg. - `errorMsg` (string | null) - `timeSeriesDataPoints` (array | null): List of time series data points with occupancy counts - `warningMsg` (string | null) ## Errors Also 400, 401, 403, 429, 500, 503 with the standard error body (`errorCode`, `errorMsg`): https://developer.rhombus.com/errors ## OpenAPI ````yaml openapi: 3.0.1 info: title: Rhombus API version: "1.0" servers: - description: Production Server url: https://api2.rhombussystems.com security: - ApiKeyAuth: [] paths: /api/report/getOccupancyCounts: post: description: |- Returns the estimated occupancy count for a specified room or area within a given time range. This endpoint allows you to monitor occupancy trends over time or retrieve a single count for a defined interval. Important: An occupancy region must be defined in the Rhombus Console before using this endpoint. You can optionally specify an interval (e.g., MINUTELY, QUARTERHOURLY, HOURLY ...) to retrieve occupancy counts broken down by sub-intervals between startTime and endTime. If no interval is provided, a single occupancy count is returned for the entire duration between startTime and endTime. operationId: getOccupancyCounts parameters: - description: "Authentication scheme identifier. Use `api-token` or `partner-api-token` with the `x-auth-apikey` header, `api` or `partner-api` with `x-auth-apikey` plus a client certificate, `api-oauth-token` or `partner-api-oauth-token` with `x-auth-access-token`, and `federated-token` with `x-auth-ft`. A request with `Authorization: Bearer ` and no `x-auth-scheme` is treated as OAuth, and `federated-token` may also be sent as the `x-auth-scheme` and `x-auth-ft` query parameters." example: api-token in: header name: x-auth-scheme required: false schema: default: api-token enum: - api-token - api - api-oauth-token - federated-token - partner-api-token - partner-api - partner-api-oauth-token type: string - description: "Client organization UUID (22-character RUUID), for partner credentials only. With it the call runs in that client organization with the partner support authority's role. Without it a partner credential runs as the partner organization, which outside the partner endpoints is deprecated (responses carry `Deprecation` and `Sunset: Tue, 05 Jan 2027 00:00:00 GMT`). A malformed value returns 400 `INVALID_AUTH_ORG`; a client organization the partner cannot access returns 403 `PARTNER_CLIENT_ACCESS_DENIED`." in: header name: x-auth-org required: false schema: format: RUUID maxLength: 22 minLength: 22 type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/Report_GetOccupancyCountsWSRequest" responses: "200": content: application/json: schema: $ref: "#/components/schemas/Report_GetOccupancyCountsWSResponse" description: OK "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "429": $ref: "#/components/responses/TooManyRequests" "500": $ref: "#/components/responses/InternalServerError" "503": $ref: "#/components/responses/ServiceUnavailable" security: - ApiKeyAuth: [] - oauth2: - read summary: Get occupancy counts tags: - Report Webservice components: schemas: Report_GetOccupancyCountsWSRequest: description: Request object for getting occupancy counts from a device. properties: deviceUuid: description: RUUID with optional appended facet information example: AAAAAAAAAAAAAAAAAAAAAA.v0 format: DeviceFacetUuid nullable: true type: string endTimeMs: description: The end timestamp (in Unix epoch milliseconds) of the selected interval example: 1640998800000 format: int64 nullable: true type: integer interval: $ref: "#/components/schemas/ReportIntervalEnum" startTimeMs: description: The start timestamp (in Unix epoch milliseconds) of the selected interval example: 1640995200000 format: int64 nullable: true type: integer type: object ReportIntervalEnum: description: Report interval for filtering face events enum: - MINUTELY - QUARTERHOURLY - HOURLY - DAILY - WEEKLY - MONTHLY type: string Report_GetOccupancyCountsWSResponse: description: Response object for getting occupancy counts from a device. properties: error: nullable: true type: boolean errorCode: description: Stable, machine-readable code for the failure (one of the ApiErrorCode catalog) when error is true. Branch on this, not on errorMsg. nullable: true type: string errorMsg: nullable: true type: string timeSeriesDataPoints: description: List of time series data points with occupancy counts items: $ref: "#/components/schemas/Report_TimeSeriesDataPointV2ExtendedType" nullable: true type: array warningMsg: nullable: true type: string type: object Report_TimeSeriesDataPointV2ExtendedType: description: Extended time series data point with additional timestamp information. properties: approximateTimestampMsMap: additionalProperties: description: A mapping of timestamps (in Unix epoch milliseconds) that indicate, for each type and interval, the point in time where the aggregated occupancy count is closest to the occupancy observed in the corresponding video segment format: int64 nullable: true type: integer description: A mapping of timestamps (in Unix epoch milliseconds) that indicate, for each type and interval, the point in time where the aggregated occupancy count is closest to the occupancy observed in the corresponding video segment nullable: true type: object dateLocal: nullable: true type: string dateUtc: nullable: true type: string eventCountMap: additionalProperties: format: int64 nullable: true type: integer nullable: true type: object reportingDevicesMap: additionalProperties: items: description: RUUID with optional appended facet information example: AAAAAAAAAAAAAAAAAAAAAA.v0 format: DeviceFacetUuid nullable: true type: string nullable: true type: array nullable: true type: object timestampMs: description: The representative timestamp (in Unix epoch milliseconds) for the interval example: 1640995200000 format: int64 nullable: true type: integer type: object securitySchemes: ApiKeyAuth: description: Your Rhombus API key. Must be accompanied by the `x-auth-scheme` header set to `api-token` (or `partner-api-token` for partner endpoints). in: header name: x-auth-apikey type: apiKey oauth2: description: 'OAuth 2.0 authorization code flow with PKCE (`S256`). Send the access token as `Authorization: Bearer `. Each operation lists the scopes it requires; a token without them is refused 403 with `WWW-Authenticate: Bearer error="insufficient_scope"`.' flows: authorizationCode: authorizationUrl: https://console.rhombus.com/oauth/authorize refreshUrl: https://auth-web.rhombussystems.com/oauth/token scopes: physical: Unlock doors and elevators, lockdown, alarms, speakers and robots read: View cameras, footage and settings write: Change settings and data tokenUrl: https://auth-web.rhombussystems.com/oauth/token type: oauth2 ````