Get worker turnover historical report for a specific employer
POST/v1/reporting/:employer_id/reports/worker_turnover/historical
Retrieves historical turnover metrics by period: total/voluntary/involuntary turnover, headcount, rehires, and turnover rate. Period range is computed from to_date and period_granularity (e.g. 12 weeks, 12 months, 12 quarters, 12 years).
Request
Path Parameters
Use me (recommended) to resolve the employer associated with your OAuth credentials, or pass your numeric employer ID. The value must match the employer your token is issued for.
Query Parameters
End date of the report (ISO 8601 format: YYYY-MM-DD). Period range is computed from this and period_granularity.
Period granularity. Must be one of: WEEK, MONTH, QUARTER, YEAR
Responses
- 200
- 400
- 401
- 403
- 404
- 429
- 500
- 504
Successfully retrieved historical turnover report
- */*
- Schema
- Example (from schema)
Schema
Array [
]
metadata
object
periods
object[]
{ "metadata": { "employer_id": 0, "to_date": "string", "period_from": "string", "period_granularity": "string", "venue_ids": [ 0 ], "area_ids": [ 0 ], "generated_at": "2026-07-07T10:51:42.821Z" }, "periods": [ { "date": "string", "granularity": "string", "total_turnover": 0, "voluntary_turnover": 0, "involuntary_turnover": 0, "headcount": 0, "rehires": 0, "turnover_rate": 0 } ]}Invalid request parameters. The response body follows the ErrorResponse schema.
- application/json
- Schema
- Example (from schema)
Schema
Human-readable error message.
Machine-readable error classification (e.g. VALIDATION_ERROR, TIMEOUT_ERROR, CIRCUIT_BREAKER_OPEN).
Whether the request can be safely retried.
When the error occurred.
{ "error": "string", "errorType": "string", "retryable": true, "timestamp": "2026-07-07T10:51:42.821Z"}Missing or invalid Bearer token.
The authenticated client is not authorized for the requested employer_id. The employer_id in the path must match the employer your token is issued for.
Unknown endpoint, or reporting access is not enabled for this client.
Rate limit exceeded. Retry after the interval indicated by the Retry-After response header.
Internal server error. The response body follows the ErrorResponse schema.
- application/json
- Schema
- Example (from schema)
Schema
Human-readable error message.
Machine-readable error classification (e.g. VALIDATION_ERROR, TIMEOUT_ERROR, CIRCUIT_BREAKER_OPEN).
Whether the request can be safely retried.
When the error occurred.
{ "error": "string", "errorType": "string", "retryable": true, "timestamp": "2026-07-07T10:51:42.821Z"}Upstream timeout. The reporting backend did not respond in time; the response body is {"error": "upstream timeout"}.