> ## Documentation Index > Fetch the complete documentation index at: https://docs.guardhousehq.com/llms.txt > Use this file to discover all available pages before exploring further. # List live operations > Returns live operational records for shifts and employees. Use filters such as date range, site, customer, employee name, subcontractor, and status to narrow results. If `startDate` or `endDate` is omitted, the API defaults to a 34-hour window around the current UTC time (`now - 17 hours` through `now + 17 hours`). Results support cursor-style pagination with `referenceId`, `referenceDateTime`, `direction`, and the `nextPageParameter` value returned by the previous response. Requires a public API key with `KeyType=liveops`. ## OpenAPI ````yaml /api-reference/openapi.json get /api/external/liveops openapi: 3.1.0 info: title: Guardhouse API version: 1.0.0 description: >- The Guardhouse API gives external systems programmatic access to incident reports, timesheets, staff, customers, sites, and webhook event subscriptions. All endpoints return a consistent envelope (`ApiResponse`, `ApiPagedResponse`, or `ApiPostPagedResponse`). Authentication is a two-step flow: exchange a long-lived **API key** for a short-lived **JWT bearer token**, then send the bearer on every subsequent request. contact: name: Guardhouse Support license: name: Proprietary servers: - url: https://gateway-api.guardhousehq.com description: AU production - url: https://gateway-api.guardhousehq.co.uk description: UK production security: - bearerAuth: [] subscriptionKey: [] tags: - name: Authentication description: >- Exchange a long-lived API key for a short-lived JWT bearer token. The token must be sent as `Authorization: Bearer ` on every subsequent request. - name: Incident Reports description: >- List, fetch, and export incident reports submitted against your customers and sites. Requires an API key with `KeyType=incidentreport`. - name: Timesheets description: List timesheet entries and fetch per-entry rate breakdowns. - name: Live Operations description: >- Retrieve live shift and employee operational data, including clock-in status, location, welfare checks, and license details. - name: Staff description: >- List, create, and update employees and their security licenses. Read endpoints (`GET /api/external/staffs`, `GET /api/external/staffs/{id}/licenses`) are accessible with any valid Public API key. Write endpoints (`POST`, `PATCH`, `GET /staffs/search`) require `KeyType=developer`. - name: Customers description: List customer records visible to your API key. - name: Sites description: List sites visible to your API key. - name: Webhooks description: >- Manage webhook subscribers and event subscriptions so Guardhouse can notify your systems when incident reports or timesheets change. Requires an API key with `KeyType=developer`. - name: Login Audit description: >- Read-only access to login activity (successful logins, failed logins, and reserved logout events) for your company. **Requires an API key issued with the `login-audits.read` entitlement scope** — keys without this special scope are rejected at the auth layer with `403 Forbidden`. Tokens minted from such a key carry `login-audits.read` in their `Scope` claim, which is what the endpoint checks. paths: /api/external/liveops: get: tags: - Live Operations summary: List live operations description: >- Returns live operational records for shifts and employees. Use filters such as date range, site, customer, employee name, subcontractor, and status to narrow results. If `startDate` or `endDate` is omitted, the API defaults to a 34-hour window around the current UTC time (`now - 17 hours` through `now + 17 hours`). Results support cursor-style pagination with `referenceId`, `referenceDateTime`, `direction`, and the `nextPageParameter` value returned by the previous response. Requires a public API key with `KeyType=liveops`. parameters: - name: startDate in: query description: Start date for filtering results (ISO-8601 date-time). schema: type: string format: date-time - name: endDate in: query description: End date for filtering results (ISO-8601 date-time). schema: type: string format: date-time - name: siteName in: query description: Filter by site name. schema: type: string - name: siteId in: query description: Filter by site ID. schema: type: string - name: customerName in: query description: Filter by customer name. schema: type: string - name: customerId in: query description: Filter by customer ID. schema: type: string - name: fullName in: query description: Filter by employee full name. schema: type: string - name: subcontractorName in: query description: Filter by subcontractor name. schema: type: string - name: status in: query description: Filter by event status, such as `CLOCKED IN`. schema: type: string - name: limit in: query description: Maximum number of records to return. schema: type: integer format: int32 default: 100 - name: referenceId in: query description: >- Unique ID of the last record received. Use with `referenceDateTime` to fetch records after this cursor. schema: type: integer format: int32 - name: referenceName in: query description: Cursor anchor name when paginating across name-sorted results. schema: type: string - name: referenceDateTime in: query description: >- Timestamp of the last record received. Use with `referenceId` to fetch records after this cursor. schema: type: string format: date-time - name: searchText in: query description: Free-text search filter. schema: type: string - name: direction in: query description: Cursor pagination direction. schema: type: string enum: - next - prev default: next responses: '200': description: Live operations response content: application/json: schema: $ref: '#/components/schemas/LiveOperationsEnvelope' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' components: schemas: LiveOperationsEnvelope: type: object description: Live Operations API envelope. allOf: - $ref: '#/components/schemas/BaseServiceResponse' - type: object properties: data: type: array items: $ref: '#/components/schemas/LiveOperationsRecord' nextPageParameter: type: string nullable: true description: >- Serialized cursor for the next page, for example `{"ReferenceId":24915663,"ReferenceDateTime":"2025-07-25T09:00:00"}`. prevPageParameter: type: string nullable: true BaseServiceResponse: type: object properties: isSuccess: type: boolean statusMessage: type: string status: type: integer format: int32 errorMessages: type: array items: type: object additionalProperties: true errorMessagesAsString: type: string LiveOperationsRecord: type: object properties: companyName: type: string name: type: string siteName: type: string customerName: type: string startTime: type: string format: date-time nullable: true endTime: type: string format: date-time nullable: true timeIn: type: string format: date-time nullable: true timeOut: type: string format: date-time nullable: true status: type: string example: CLOCKED IN inSignatureUrl: type: string outSignatureUrl: type: string inPhotoUrl: type: string outPhotoUrl: type: string inLatitude: type: number format: double nullable: true inLongitude: type: number format: double nullable: true outLatitude: type: number format: double nullable: true outLongitude: type: number format: double nullable: true startTimeTZ: type: string format: date-time nullable: true endTimeTZ: type: string format: date-time nullable: true timeInTZ: type: string format: date-time nullable: true timeOutTZ: type: string format: date-time nullable: true subcontractorName: type: string eventID: type: string mobile: type: string email: type: string format: email address: type: string calledAt: type: string format: date-time nullable: true calledBy: type: integer format: int32 nullable: true entryTypeID: type: integer format: int32 nullable: true isClockInOffSite: type: boolean nullable: true isClockOutOffSite: type: boolean nullable: true calledByFullName: type: string inEnteredByFullName: type: string outEnteredByFullName: type: string licenses: type: array items: type: object additionalProperties: true welfareCheckResponses: type: array items: $ref: '#/components/schemas/WelfareCheckResponse' welfareCheckNotifResponses: type: array items: $ref: '#/components/schemas/WelfareCheckResponse' statusText: type: string publishedShiftID: type: integer format: int32 nullable: true sitePositionName: type: string shiftId: type: integer format: int32 nullable: true LoginAuditEnvelope: type: object description: >- Standard `{ data, errors, meta }` envelope used by Login Audit endpoints. Differs from the legacy `ApiResponse` envelope used by older endpoints. properties: data: nullable: true description: Endpoint-specific payload. `null` when `errors` is populated. errors: type: array nullable: true items: $ref: '#/components/schemas/LoginAuditEnvelopeError' meta: $ref: '#/components/schemas/LoginAuditEnvelopeMeta' ApiResponse: type: object description: The standard envelope for every JSON endpoint. properties: status: $ref: '#/components/schemas/Status' data: description: Endpoint-specific payload. `null` when an error occurred. nullable: true count: type: integer format: int32 nullable: true message: type: string errors: type: array items: $ref: '#/components/schemas/Error' WelfareCheckResponse: type: object properties: timesheetEntryId: type: integer format: int32 welfareCheckId: type: integer format: int32 dateSent: type: string format: date-time hasResponse: type: boolean type: type: string nullable: true description: Notification type, such as `PN`. parentWelfareCheckId: type: integer format: int32 managerCheck: type: boolean managerEmployee: type: string nullable: true followUps: type: array items: type: object additionalProperties: true LoginAuditEnvelopeError: type: object properties: code: type: string message: type: string field: type: string nullable: true LoginAuditEnvelopeMeta: type: object properties: traceId: type: string description: Server-side trace identifier — include in support requests. timestampUtc: type: string format: date-time nextPageEndpoint: type: string nullable: true prevPageEndpoint: type: string nullable: true Status: type: object properties: code: type: integer format: int32 description: Numeric service result code. `0` indicates success. errorMessage: type: string description: Human-readable error message; empty on success. Error: type: object properties: code: type: integer format: int32 default: 100 message: type: string responses: Unauthorized: description: The bearer token is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/LoginAuditEnvelope' Forbidden: description: >- The bearer token is missing the required policy or `KeyType` claim, or the resource is outside your API key's scope. content: application/json: schema: $ref: '#/components/schemas/ApiResponse' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- JWT issued by `POST /api/external/token/request`. Send as `Authorization: Bearer `. subscriptionKey: type: apiKey in: header name: external-gh-apim-sub-key description: >- Guardhouse API Management subscription key. Required on every request. The same value is used by all API consumers within a region — contact Guardhouse Support for the subscription key. ````