--- updatedAt: 2026-06-03T14:36:43.000Z agentTools: projectIndex: https://developer.personio.de/llms.txt --- # Retrieves a report. Retrieves a report for the provided ID. # OpenAPI definition ```json { "openapi": "3.0.3", "info": { "title": "Public API - Reporting Engine Service", "version": "2.0.0", "description": "Collection of endpoints to manage the Analytics Report Builder." }, "servers": [ { "url": "https://api.personio.de", "description": "Relative url for Public API reporting service v2." } ], "security": [ { "BearerAuth": [] } ], "paths": { "/v2/reports/{id}": { "get": { "summary": "Retrieves a report.", "description": "Retrieves a report for the provided ID.", "x-path-examples": { "200 Get Report": { "value": "/public-api/v2/reports/083f72d2-c20a-4275-9f6f-80306296e8e1" }, "200 Get Report with cursor": { "value": "/public-api/v2/reports/083f72d2-c20a-4275-9f6f-80306296e8e1", "query": "cursor=eyJvZmZzZXQiOjAsInRhYmxlUXVlcnkiOnsicm93IjoiZW1wbG95ZWUiLCJ" }, "200 Get Report with locale and limit": { "value": "/public-api/v2/reports/083f72d2-c20a-4275-9f6f-80306296e8e1", "query": "locale=en&limit=10" }, "404 Get Report Not Found": { "value": "/public-api/v2/reports/083f72d2-c20a-4275-9f6f-80306296e8e1XXX" }, "400 Request with invalid limit": { "value": "/public-api/v2/reports/083f72d2-c20a-4275-9f6f-80306296e8e1", "query": "limit=xxx" } }, "operationId": "getReport", "tags": [ "Reports" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "locale", "description": "Locale of current user", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Locale" } }, { "name": "cursor", "description": "An encoded opaque value containing row, timerange, columns, filters, grouping and sorting parameters. Either a cursor or body containing these parameters should be specified at one time.", "in": "query", "required": false, "schema": { "type": "string", "example": 1 } }, { "name": "limit", "description": "Max number of table rows returned in the response. If absent, all rows are returned.", "in": "query", "required": false, "schema": { "type": "number", "example": 25 } } ], "responses": { "200": { "description": "Single report response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetReportResponse" }, "examples": { "200 Get Report": { "$ref": "#/components/examples/GetReportResponseExample" }, "200 Get Report with cursor": { "$ref": "#/components/examples/GetReportResponseExample" }, "200 Get Report with locale and limit": { "$ref": "#/components/examples/GetReportResponseExample" } } } } }, "400": { "$ref": "#/components/responses/400Response" }, "404": { "$ref": "#/components/responses/404Response" } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "responses": { "404Response": { "description": "Not Found Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "404 Get Report Not Found": { "$ref": "#/components/examples/404ResponseExample" } } } } }, "400Response": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "400 Request with invalid limit": { "$ref": "#/components/examples/400ResponseLimitExample" } } } } } }, "schemas": { "DateField": { "type": "string", "title": "Report Date Field Identifier", "description": "The id of the date attribute to use for the point in time and time range filters. If not specified, the query will use the date field associated with the queried metric / attribute. Which is the validity period for the periodic snapshot metrics, the transaction date for the transactional metrics and different for each accumlating snapshot metric." }, "GroupByTime": { "type": "string", "title": "Time Grouping Interval", "description": "Specifies the time interval for grouping report results (e.g., days, weeks, months).", "enum": [ "days", "weeks", "months", "quarters", "years", "whole_timerange" ] }, "DateRange": { "type": "object", "title": "Date range", "description": "Required if date_range_option is custom.", "required": [ "from", "to" ], "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } } }, "TableQueryColumn": { "type": "object", "title": "Report Table Query Column", "description": "Describes a column in the API response for table queries.", "required": [ "attribute" ], "properties": { "attribute": { "type": "string" }, "column_name": { "description": "(Optional) Name of the column which will be used as key in result object and as sorting id, if not specified - defaults to attribute name.", "type": "string" }, "display": { "type": "string" }, "description": { "type": "string" }, "data_type": { "$ref": "#/components/schemas/AttributeDataType" }, "summarize_by": { "$ref": "#/components/schemas/AttributeSummarizeBy" } } }, "AttributeDataType": { "title": "Attribute data type", "description": "The data type of the attribute (e.g., string, option, date, decimal).", "type": "string", "enum": [ "string", "option", "date", "decimal", "integer", "datetime", "time", "monetary_amount", "nested_list", "percentage" ] }, "AttributeSummarizeBy": { "title": "Summarize By options for the attribute", "description": "The method used to summarize attribute values (e.g., avg, sum, count).", "type": "string", "enum": [ "avg", "sum", "count", "count_non_distinct", "total" ] }, "ErrorResponse": { "type": "object", "title": "API Error Response", "description": "Standardized error response object containing one or more error details.", "required": [ "errors" ], "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ApiError" } } } }, "ApiError": { "type": "object", "title": "API Error Detail", "description": "Represents a single error, including status code, error title, unique identifier, and detailed message.", "required": [ "status", "title" ], "properties": { "status": { "type": "string" }, "title": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "detail": { "type": "string" } } }, "GetReportResponse": { "type": "object", "title": "Get Report Response", "description": "The response object for retrieving a specific report, including configuration and data.", "properties": { "report_config": { "$ref": "#/components/schemas/ReportConfig" }, "_data": { "type": "array", "description": "array of report data rows", "items": { "$ref": "#/components/schemas/ReportRow" } }, "_meta": { "type": "object", "required": [ "columns" ], "properties": { "links": { "type": "object", "properties": { "self": { "type": "string", "example": "https://api.personio.de/public-api/v2/reports/083f72d2-c20a-4275-9f6f-80306296e8e1?cursor=eyJyb3ciOiJlbXBsb3llZSIsInRpbWVyYW5nZSI6eyJmcm9tIjoiMjAyMC0wMS0zMSIsInRvIjoiMjAyMS0wMS0zMSJ9fQ==&limit=10" }, "next": { "type": "string", "example": "https://api.personio.de/public-api/v2/reports/083f72d2-c20a-4275-9f6f-80306296e8e1?cursor=eyJyb3ciOiJlbXBsb3llZSIsInRpbWVyYW5nZSI6eyJmcm9tIjoiMjAyMC0wMS0zMSIsInRvIjoiMjAyMS0wMS0zMSJ9fQ==&limit=10" } } }, "columns": { "type": "array", "description": "meta information of each data column.", "items": { "type": "object", "title": "response column", "required": [ "name", "display", "type" ], "properties": { "name": { "type": "string" }, "display": { "type": "string" }, "type": { "$ref": "#/components/schemas/MetaType" } } } } } } } }, "ReportConfig": { "type": "object", "title": "Report Configuration", "description": "Configuration details for a specific report, including its name, title, description, and report-specific settings such as chart type, metrics, and filters.", "required": [ "name", "title", "description", "config" ], "properties": { "name": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "config": { "$ref": "#/components/schemas/ReportConfigDetails" }, "historical_report": { "$ref": "#/components/schemas/HistoricalReportConfig" } } }, "ReportConfigDetails": { "type": "object", "title": "Report Configuration Details", "description": "Detailed configuration options for report generation, including base attributes, metrics, summarization methods, table settings, segmentation, sorting, filters, and time-based configurations.", "required": [ "title", "visualization_type", "timerange", "columns" ], "properties": { "title": { "type": "string", "description": "Title of the report" }, "visualization_type": { "$ref": "#/components/schemas/VisualizationType" }, "timerange": { "$ref": "#/components/schemas/ReportTimeframe" }, "columns": { "type": "array", "description": "The columns to be displayed in the chart/table", "items": { "$ref": "#/components/schemas/ReportColumn" } }, "sort_bys": { "type": "array", "description": "Sort configuration for the chart/table", "items": { "$ref": "#/components/schemas/ReportField" } }, "group_bys": { "type": "array", "items": { "$ref": "#/components/schemas/ReportField" } }, "filter_group": { "$ref": "#/components/schemas/FilterGroup" }, "row_calculation": { "$ref": "#/components/schemas/TableCalculation" }, "column_calculation": { "$ref": "#/components/schemas/TableCalculation" } } }, "VisualizationType": { "type": "string", "title": "Report Visualization Type", "description": "The type of visualization used for the report", "enum": [ "treemap", "bar", "column", "donut", "line", "table" ] }, "ReportTimeframe": { "type": "object", "title": "Report Timeframe", "description": "Time frame configuration for report", "required": [ "date_range_option" ], "properties": { "date_range_option": { "type": "string", "enum": [ "custom", "today", "last-week", "last-month", "last-3-months", "last-6-months", "last-12-months", "last-year", "this-week", "this-month", "this-quarter", "this-year", "next-13-weeks", "next-26-weeks" ] }, "group_by": { "$ref": "#/components/schemas/GroupByTime" }, "date_range": { "$ref": "#/components/schemas/DateRange" }, "date_field": { "$ref": "#/components/schemas/DateField" } } }, "ReportColumn": { "type": "object", "title": "Report Column", "description": "Configuration for a single column in the report", "required": [ "attribute" ], "properties": { "attribute": { "type": "string" }, "summarize_by": { "$ref": "#/components/schemas/AttributeSummarizeBy" }, "column_name": { "type": "string", "description": "Name to be displayed in the table header for this column" } } }, "ReportField": { "type": "object", "title": "Report Field", "description": "A generic field reference used for sorting and grouping", "required": [ "id", "desc" ], "properties": { "id": { "type": "string" }, "desc": { "type": "boolean" } } }, "TableCalculation": { "type": "string", "title": "Table Calculation Type", "description": "Type of calculation to be performed on table data", "enum": [ "none", "sum", "count", "average" ] }, "Locale": { "title": "Locale of current user", "description": "The locale/language setting used for the current user.", "type": "string", "default": "en" }, "ReportRow": { "type": "array", "title": "Report Row", "description": "Row for a report results, rows can be grouped by the column selected in the report configuration.", "items": { "$ref": "#/components/schemas/ReportRowItem" } }, "ReportRowItem": { "type": "object", "properties": { "attribute_id": { "type": "string" }, "numeric_value": { "$ref": "#/components/schemas/NumericAttributeResponse" }, "percentage_value": { "$ref": "#/components/schemas/PercentageAttributeResponse" }, "string_value": { "$ref": "#/components/schemas/StringAttributeResponse" }, "options_value": { "$ref": "#/components/schemas/OptionsResponse" }, "monetary_value": { "$ref": "#/components/schemas/MonetaryResponse" }, "time_range_value": { "$ref": "#/components/schemas/TimeRangeResponse" } }, "required": [ "attribute_id" ] }, "NumericAttributeResponse": { "type": "object", "required": [ "number" ], "properties": { "number": { "type": "number" } }, "description": "Response for numeric attributes." }, "PercentageAttributeResponse": { "type": "object", "required": [ "percentage" ], "properties": { "percentage": { "type": "number" } }, "description": "Response for percentage attributes." }, "StringAttributeResponse": { "type": "object", "required": [ "value" ], "properties": { "value": { "type": "string" } }, "description": "Response for string attributes." }, "OptionsResponse": { "type": "object", "required": [ "options" ], "properties": { "options": { "type": "array", "items": { "$ref": "#/components/schemas/OptionsResponseOptionsInner" } } }, "description": "Response for option attributes." }, "OptionsResponseOptionsInner": { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string" }, "value": { "type": "string" } } }, "MonetaryResponse": { "type": "object", "required": [ "currency", "monetary_value" ], "properties": { "currency": { "type": "string" }, "monetary_value": { "type": "number" } }, "description": "Response for monetary attributes." }, "TimeRangeResponse": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } }, "description": "Response for time range attributes." }, "MetaType": { "type": "string", "title": "Field Metadata Type", "description": "The data type of a metadata field in the report schema.", "enum": [ "integer", "timestamp", "percentage", "percentage_growth", "decimal", "string", "time_range", "option", "division", "datetime", "time", "monetary_amount", "nested_list" ] }, "FilterGroup": { "type": "object", "title": "Filter Group.", "description": "A group of filter items to be used in the report conditions.", "required": [ "operator", "filters" ], "properties": { "operator": { "type": "string", "enum": [ "and", "or" ], "description": "Specifies the logical operator for combining filters within this group." }, "filters": { "type": "array", "description": "An array that can contain other FilterGroups or individual FilterItems.", "items": { "oneOf": [ { "$ref": "#/components/schemas/FilterItem" }, { "$ref": "#/components/schemas/FilterGroup" } ] } } } }, "FilterItem": { "type": "object", "title": "Filter Item.", "description": "A single filter item to be used in the report conditions.", "required": [ "id", "value" ], "properties": { "id": { "type": "string", "description": "The attribute id on which the filter is applied." }, "value": { "type": "object", "required": [ "condition", "value" ], "properties": { "condition": { "$ref": "#/components/schemas/FilterCondition" }, "value": { "nullable": true, "title": "Filter Value.", "type": "object", "description": "The value to compare against. Type depends on the FilterCondition and attribute type." } } } } }, "FilterCondition": { "type": "string", "title": "Filter Conditions.", "description": "The type of comparison conditions to be performed.", "enum": [ "contains", "does_not_contain", "equals", "does_not_equal", "starts_with", "ends_with", "is_on", "is_before", "is_on_or_before", "is_after", "is_on_or_after", "is_within_range", "is_outside_of_range", "is_less_than", "is_less_than_or_equal", "is_greater_than", "is_greater_than_or_equal", "is_empty", "is_not_empty" ] }, "HistoricalReportConfig": { "type": "object", "title": "Historical Report Configuration", "description": "Historical report configuration options for tracking changes over time", "required": [ "people_identifiers", "time_frame_config" ], "properties": { "sort_bys": { "type": "array", "description": "Sort configuration for the historical report", "items": { "$ref": "#/components/schemas/ReportField" } }, "filter_group": { "$ref": "#/components/schemas/FilterGroup" }, "time_frame_config": { "$ref": "#/components/schemas/ReportTimeframe" }, "people_identifiers": { "$ref": "#/components/schemas/PeopleIdentifiers" }, "show_effective_date_column": { "type": "boolean", "description": "Setting for showing/hiding the \"effective_date\" column" }, "attributes": { "type": "array", "description": "Array of attributes to include in the historical report", "items": { "$ref": "#/components/schemas/TableQueryColumn" } }, "group_bys": { "type": "array", "description": "Group by configuration for the historical report", "items": { "$ref": "#/components/schemas/ReportField" } } } }, "PeopleIdentifiers": { "type": "array", "title": "People Identifiers", "description": "Array of attributes that are used for people identification, e.g. [\"first_name\",\"last_name\"]", "minItems": 1, "items": { "type": "object", "required": [ "attribute" ], "properties": { "attribute": { "type": "string", "description": "The attribute name used for identification" } } } } }, "examples": { "404ResponseExample": { "value": { "errors": [ { "status": "404", "title": "Not Found", "id": "404e8400-e29b-41d4-a716-446655440000", "detail": "Cursor returned no rows" } ] } }, "400ResponseLimitExample": { "value": { "errors": [ { "status": "400", "title": "Bad Request", "id": "400e8400-e29b-41d4-a716-446655440002", "detail": "Invalid parameter 'limit': Failed to convert value" } ] } }, "GetReportResponseExample": { "value": { "report_config": { "name": "report", "title": "My report", "description": "Report description", "config": { "chart_type": "column", "metric": "headcount", "summarize_by": "count", "segment_by": [ "contract_type" ], "sort_by": [ { "id": "headcount", "desc": true } ], "filter_group": { "operator": "and", "filters": [ { "id": "first_name", "value": { "condition": "equals", "value": "Sherlock" } }, { "id": "department_id", "value": { "condition": "contains", "value": [ "sales", "marketing" ] } } ] }, "point_in_time_config": { "date_option": "custom", "date": "2023-01-01" } } }, "_data": [ [ { "attribute_id": "status", "numeric_value": null, "percentage_value": null, "string_value": null, "options_value": { "options": [ { "key": "active", "value": "Active" } ] }, "monetary_value": null, "time_range_value": null }, { "attribute_id": "gender", "numeric_value": null, "percentage_value": null, "string_value": null, "options_value": { "options": [ { "key": "male", "value": "Male" } ] }, "monetary_value": null, "time_range_value": null }, { "attribute_id": "headcount", "numeric_value": { "number": 1 }, "percentage_value": null, "string_value": null, "options_value": null, "monetary_value": null, "time_range_value": null }, { "attribute_id": "time_range", "numeric_value": null, "percentage_value": null, "string_value": null, "options_value": null, "monetary_value": null, "time_range_value": { "from": "2025-07-01", "to": "2025-07-17" } }, { "attribute_id": "first_name", "numeric_value": null, "percentage_value": null, "string_value": { "value": "John" }, "options_value": null, "monetary_value": null, "time_range_value": null }, { "attribute_id": "salary", "numeric_value": null, "percentage_value": null, "string_value": null, "options_value": null, "monetary_value": { "currency": "EUR", "monetary_value": 75000 }, "time_range_value": null }, { "attribute_id": "absence_rate", "numeric_value": null, "percentage_value": { "percentage": 2.5 }, "string_value": null, "options_value": null, "monetary_value": null, "time_range_value": null }, { "attribute_id": "performance_ratio", "numeric_value": null, "percentage_value": { "percentage": 85 }, "string_value": null, "options_value": null, "monetary_value": null, "time_range_value": null } ], [ { "attribute_id": "status", "numeric_value": null, "percentage_value": null, "string_value": null, "options_value": { "options": [ { "key": "active", "value": "Active" } ] }, "monetary_value": null, "time_range_value": null }, { "attribute_id": "gender", "numeric_value": null, "percentage_value": null, "string_value": null, "options_value": { "options": [ { "key": "female", "value": "Female" } ] }, "monetary_value": null, "time_range_value": null }, { "attribute_id": "headcount", "numeric_value": { "number": 1 }, "percentage_value": null, "string_value": null, "options_value": null, "monetary_value": null, "time_range_value": null }, { "attribute_id": "time_range", "numeric_value": null, "percentage_value": null, "string_value": null, "options_value": null, "monetary_value": null, "time_range_value": { "from": "2025-07-01", "to": "2025-07-31" } }, { "attribute_id": "first_name", "numeric_value": null, "percentage_value": null, "string_value": { "value": "Jane" }, "options_value": null, "monetary_value": null, "time_range_value": null }, { "attribute_id": "salary", "numeric_value": null, "percentage_value": null, "string_value": null, "options_value": null, "monetary_value": { "currency": "USD", "monetary_value": 82000 }, "time_range_value": null }, { "attribute_id": "absence_rate", "numeric_value": null, "percentage_value": { "percentage": 1.5 }, "string_value": null, "options_value": null, "monetary_value": null, "time_range_value": null }, { "attribute_id": "performance_ratio", "numeric_value": null, "percentage_value": { "percentage": 92 }, "string_value": null, "options_value": null, "monetary_value": null, "time_range_value": null } ] ], "_meta": { "links": { "self": "https://api.personio.de/public-api/v2/reports/083f72d2-c20a-4275-9f6f-80306296e8e1?cursor=eyJyb3ciOiJlbXBsb3llZSIsInRpbWVyYW5nZSI6eyJmcm9tIjoiMjAyMC0wMS0zMSIsInRvIjoiMjAyMS0wMS0zMSJ9fQ==&limit=10", "next": "https://api.personio.de/public-api/v2/reports/083f72d2-c20a-4275-9f6f-80306296e8e1?cursor=eyJyb3ciOiJlbXBsb3llZSIsInRpbWVyYW5nZSI6eyJmcm9tIjoiMjAyMC0wMS0zMSIsInRvIjoiMjAyMS0wMS0zMSJ9fQ==&limit=10" }, "columns": [ { "name": "status", "display": "Status", "type": "option" }, { "name": "gender", "display": "Gender", "type": "option" }, { "name": "headcount", "display": "Headcount", "type": "integer" }, { "name": "time_range", "display": "Time Range", "type": "time_range" }, { "name": "first_name", "display": "First Name", "type": "string" }, { "name": "salary", "display": "Salary", "type": "monetary_amount" }, { "name": "absence_rate", "display": "Absence Rate", "type": "percentage" }, { "name": "performance_ratio", "display": "Performance Ratio", "type": "decimal" } ] } } } } } } ```