> ## Documentation Index > Fetch the complete documentation index at: https://developers.partoo.co/llms.txt > Use this file to discover all available pages before exploring further. # Feedback analytics metrics > **⚠️ This feature is available only for organisations subscribed to Feedback Management. ⚠️** Retrieve aggregated feedback analytics data for your organisation. A request is composed of: - One or more **`metrics`** — the data you want to compute (required) - An optional **`dimensions`** — how the data is grouped - If omitted, the request returns the aggregated totals across all data matching the filters - An optional **`order_by`** — how the rows are sorted - **Filters** to narrow the data: - By business (`business__in`, `business__notin`) - By group or group section (`groups`, `group_section_id`) - By date range (`filter_date__gte`, `filter_date__lte`) - By survey or field (`survey__in`, `survey_field__in`, `survey_field_type__in`) - By NPS score (`result_nps_score__in`) - By free-text comment (`verbatim_query`) - By data quality issues (`issues__in`, `issues__notin`) - By business location (`city`, `query`) **Metrics** are grouped into five categories: | Category | Prefix | Examples | |---|---|---| | Survey | `survey.` | `survey.response_rate`, `survey.nb__sent` | | CSAT | `result.csat.` | `result.csat.score`, `result.csat.avg_score` | | NPS | `result.nps.` | `result.nps.score`, `result.nps.promoters` | | Response | `response.` | `response.avg_response_time`, `response.method.nb__ai` | | Result field | `result_field.` | `result_field.rating`, `result_field.choices` | **Dimensions** control how rows are grouped: - Entity: `business`, `user`, `feedback_form`, `group`, `group_section`, `feedback_form_field`, `result` - Time: `day`, `month`, `year` **Excel download**: add `download=true` to receive the data as an `.xlsx` file instead of JSON. Use `table_name` to customise the filename. **Metadata**: add `metadata=true` to include full entity objects (businesses, forms, users…) alongside the `data` array. Useful for resolving IDs to display names without extra API calls. ## OpenAPI ````yaml /assets/openapi/openapi-bundled.yaml get /feedback/analytics/metrics openapi: 3.1.0 info: title: Partoo Rest API version: v2 license: name: © Copyright Partoo url: https://www.partoo.co/en/gtu-api/ x-logo: url: >- https://partoo-client-images.s3.amazonaws.com/logo-partoo-restapi-white.png description: > ## Introduction The Partoo Rest API allows you to automate all the actions that are possible to do in the Partoo Web Application. The Partoo Rest API can be used for many different purposes: - Create/update/delete your businesses & users if you are a client. - Create/subscribe/manage organizations, businesses & users if you are a reseller. - Retrieve data on businesses you have access to if you are a publisher. - ... servers: - url: https://api.partoo.co/v2 description: Production server - url: https://api.sandbox.partoo.co/v2 description: Sandbox server (dev environment for clients & partners) security: - ApiKeyAuth: [] paths: /feedback/analytics/metrics: get: tags: - Feedback analytics summary: Feedback analytics metrics description: > **⚠️ This feature is available only for organisations subscribed to Feedback Management. ⚠️** Retrieve aggregated feedback analytics data for your organisation. A request is composed of: - One or more **`metrics`** — the data you want to compute (required) - An optional **`dimensions`** — how the data is grouped - If omitted, the request returns the aggregated totals across all data matching the filters - An optional **`order_by`** — how the rows are sorted - **Filters** to narrow the data: - By business (`business__in`, `business__notin`) - By group or group section (`groups`, `group_section_id`) - By date range (`filter_date__gte`, `filter_date__lte`) - By survey or field (`survey__in`, `survey_field__in`, `survey_field_type__in`) - By NPS score (`result_nps_score__in`) - By free-text comment (`verbatim_query`) - By data quality issues (`issues__in`, `issues__notin`) - By business location (`city`, `query`) **Metrics** are grouped into five categories: | Category | Prefix | Examples | |---|---|---| | Survey | `survey.` | `survey.response_rate`, `survey.nb__sent` | | CSAT | `result.csat.` | `result.csat.score`, `result.csat.avg_score` | | NPS | `result.nps.` | `result.nps.score`, `result.nps.promoters` | | Response | `response.` | `response.avg_response_time`, `response.method.nb__ai` | | Result field | `result_field.` | `result_field.rating`, `result_field.choices` | **Dimensions** control how rows are grouped: - Entity: `business`, `user`, `feedback_form`, `group`, `group_section`, `feedback_form_field`, `result` - Time: `day`, `month`, `year` **Excel download**: add `download=true` to receive the data as an `.xlsx` file instead of JSON. Use `table_name` to customise the filename. **Metadata**: add `metadata=true` to include full entity objects (businesses, forms, users…) alongside the `data` array. Useful for resolving IDs to display names without extra API calls. operationId: getFeedbackAnalyticsMetrics parameters: - $ref: '#/components/parameters/query_metrics' - $ref: '#/components/parameters/query_dimensions' - $ref: '#/components/parameters/fm_analytics_query_order_by' - $ref: '#/components/parameters/fm_analytics_query_business__in' - $ref: '#/components/parameters/fm_analytics_query_business__notin' - $ref: '#/components/parameters/query_user__in' - $ref: '#/components/parameters/fm_analytics_query_groups' - $ref: '#/components/parameters/query_group_section_id' - $ref: '#/components/parameters/fm_analytics_query_city' - $ref: '#/components/parameters/fm_analytics_query_query' - $ref: '#/components/parameters/fm_analytics_query_filter_date__gte' - $ref: '#/components/parameters/fm_analytics_query_filter_date__lte' - $ref: '#/components/parameters/query_survey__in' - $ref: '#/components/parameters/query_survey_field__in' - $ref: '#/components/parameters/query_survey_field_type__in' - $ref: '#/components/parameters/query_result_nps_score__in' - $ref: '#/components/parameters/query_result_id__in' - $ref: '#/components/parameters/query_verbatim_query' - $ref: '#/components/parameters/query_issues__in' - $ref: '#/components/parameters/query_issues__notin' - $ref: '#/components/parameters/query_metadata' - $ref: '#/components/parameters/query_download' - $ref: '#/components/parameters/query_table_name' - $ref: '#/components/parameters/fm_analytics_query_page' - $ref: '#/components/parameters/fm_analytics_query_per_page' responses: '200': description: > OK. When `download=true`, the response is an Excel file (`.xlsx`) with a `Content-Disposition: attachment` header containing the generated filename, instead of the JSON body described below. content: application/json: schema: $ref: '#/components/schemas/FeedbackAnalyticsResponse' examples: '?metrics=result.csat.score,result.csat.avg_score': value: page: 1 count: 1 max_page: 1 data: - result.csat.score: 87.5 result.csat.avg_score: 4.38 metadata: feedback_form: null feedback_form_field: null result: null business: null group: null group_section: null user: null '?metrics=result.csat.score&dimensions=business': value: page: 1 count: 2 max_page: 1 data: - result.csat.score: 91.2 business_id: 59b2645db12ff60643ef832c - result.csat.score: 83.4 business_id: 60b2645fb12ff60643ef8344 metadata: feedback_form: null feedback_form_field: null result: null business: null group: null group_section: null user: null '?metrics=result.nps.score,result.nps.promoters&dimensions=month&filter_date__gte=2024-01-01&filter_date__lte=2024-03-31': value: page: 1 count: 3 max_page: 1 data: - result.nps.score: 42 result.nps.promoters: 58 date: '2024-01-01' - result.nps.score: 45 result.nps.promoters: 63 date: '2024-02-01' - result.nps.score: 50 result.nps.promoters: 71 date: '2024-03-01' metadata: feedback_form: null feedback_form_field: null result: null business: null group: null group_section: null user: null '?metrics=survey.response_rate,survey.nb__sent&dimensions=feedback_form&metadata=true': value: page: 1 count: 2 max_page: 1 data: - survey.response_rate: 0.72 survey.nb__sent: 250 feedback_form_id: 674d791c13c9d976e20001b1 - survey.response_rate: 0.61 survey.nb__sent: 180 feedback_form_id: 674d791c13c9d976e20001b2 metadata: feedback_form: - id: 674d791c13c9d976e20001b1 display_name: Post-visit Survey - id: 674d791c13c9d976e20001b2 display_name: Annual NPS Survey feedback_form_field: null result: null business: null group: null group_section: null user: null '?metrics=result.csat.score&dimensions=business,month&order_by=-result.csat.score': value: page: 1 count: 4 max_page: 1 data: - result.csat.score: 95 business_id: 59b2645db12ff60643ef832c date: '2024-02-01' - result.csat.score: 90 business_id: 60b2645fb12ff60643ef8344 date: '2024-02-01' - result.csat.score: 88 business_id: 59b2645db12ff60643ef832c date: '2024-01-01' - result.csat.score: 75 business_id: 60b2645fb12ff60643ef8344 date: '2024-01-01' metadata: feedback_form: null feedback_form_field: null result: null business: null group: null group_section: null user: null '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' deprecated: false components: parameters: query_metrics: in: query name: metrics required: true description: > Comma-separated list of analytics metrics to return. At least one value is required. **Survey metrics** - `survey.response_rate`: Response rate (submissions / sends) - `survey.nb__sent`: Number of surveys sent - `survey.nb__with_comments`: Number of responses with a comment - `survey.nb__without_comments`: Number of responses without a comment - `survey.total_surveys`: Total number of survey submissions - `survey.clicks`: Number of survey link clicks - `survey.respondents`: Number of unique respondents - `survey.verbatims`: Number of verbatim comments - `survey_details`: Full per-result survey details **CSAT metrics** - `result.csat.score`: CSAT score (percentage of ratings 4-5) - `result.csat.avg_score`: Average CSAT rating - `result.csat.pct__rating_5`: Percentage of 5-star ratings - `result.csat.pct__rating_4`: Percentage of 4-star ratings - `result.csat.pct__rating_3`: Percentage of 3-star ratings - `result.csat.pct__rating_2`: Percentage of 2-star ratings - `result.csat.pct__rating_1`: Percentage of 1-star ratings - `result.csat.pct__rating_1_2`: Percentage of 1-2 star ratings combined - `result.csat.rating_5`: Count of 5-star ratings - `result.csat.rating_1_2`: Count of 1-2 star ratings combined - `result.csat.total_responses`: Total number of CSAT responses **NPS metrics** - `result.nps.score`: NPS score (promoters % − detractors %) - `result.nps.promoters`: Number of promoters (score 9-10) - `result.nps.passives`: Number of passives (score 7-8) - `result.nps.detractors`: Number of detractors (score 0-6) - `result.nps.avg__score`: Average NPS raw score - `result.nps.pct__promoters`: Percentage of promoters - `result.nps.pct__detractors`: Percentage of detractors - `result.nps.pct__passives`: Percentage of passives - `result.nps.pct__with_comments`: Percentage of responses with comments - `result.nps.pct__without_comment`: Percentage of responses without comments - `result.nps.total_responses`: Total number of NPS responses **Response metrics** - `response.created.replied_under_2days`: Replies sent within 2 days - `response.created.replied_over_2days`: Replies sent after 2 days - `response.created.not_replied`: Feedback not yet replied to - `response.method.nb__manual`: Number of manual replies - `response.method.nb__ai`: Number of AI-assisted replies - `response.not_replied`: Total feedback not replied to - `response.under_2days`: Total replies under 2 days - `response.over_2days`: Total replies over 2 days - `response.avg_response_time`: Average response time (seconds) - `response.total_surveys`: Total surveys included in response stats - `response.total_responses`: Total replies sent - `response.method_ai`: Replies using AI (alias) - `response.method_manual`: Replies sent manually (alias) **Result field metrics** (use with `feedback_form_field` dimension) - `result_field.rating`: Rating value for a form field - `result_field.content`: Text content of a form field response - `result_field.choices`: Selected choices for a form field - `result_field.field_position`: Position of the field within the form - `result_field.result_count`: Number of results for a field schema: type: string example: result.csat.score,result.csat.avg_score query_dimensions: in: query name: dimensions required: false description: > Comma-separated list of dimensions to group the returned data by. If omitted, the response contains aggregated totals across all data. **Entity dimensions** - `business`: Group results by business - `user`: Group results by user - `feedback_form`: Group results by survey form - `group`: Group results by business group - `group_section`: Group results by group section - `feedback_form_field`: Group results by form field (use with `result_field.*` metrics) - `result`: Return individual feedback results (one row per result) **Date dimensions** - `day`: Group by calendar day - `month`: Group by calendar month - `year`: Group by calendar year schema: type: string enum: - business - user - feedback_form - group - group_section - feedback_form_field - result - day - month - year example: business,month fm_analytics_query_order_by: in: query name: order_by required: false description: > Comma-separated list of fields to sort by. Prefix a field name with `-` to sort in descending order; no prefix sorts ascending. Each field must be one of the `metrics` or `dimensions` values included in the request. Examples: `order_by=result.csat.score`, `order_by=-result.nps.score,business` schema: type: string example: '-result.csat.score' fm_analytics_query_business__in: in: query name: business__in required: false description: Filter results to only the specified business IDs (comma-separated). schema: type: string example: 59b2645db12ff60643ef832c,60b2645fb12ff60643ef8344 fm_analytics_query_business__notin: in: query name: business__notin required: false description: Exclude the specified business IDs from results (comma-separated). schema: type: string example: 59b2645db12ff60643ef832c query_user__in: in: query name: user__in required: false description: > Filter results to the specified user IDs (comma-separated integers). For non-admin users this is automatically restricted to their accessible users when the `user` dimension is requested. schema: type: string example: >- 6797bc826dfe97f2f60c427c,614d9d1978a067d412028333,672b8d1126ef12c5a00bfbb3 fm_analytics_query_groups: in: query name: groups required: false description: >- Filter results to businesses belonging to the specified group IDs (comma-separated integers). schema: type: string example: 1244,1245 query_group_section_id: in: query name: group_section_id required: false description: >- Filter results to businesses belonging to the specified group section ID. schema: type: integer example: 42 fm_analytics_query_city: in: query name: city required: false description: Filter results to businesses located in the specified city. schema: type: string example: Paris fm_analytics_query_query: in: query name: query required: false description: Fuzzy search businesses by name, city, or zipcode. schema: type: string fm_analytics_query_filter_date__gte: in: query name: filter_date__gte required: false description: > Return only feedback results whose date is greater than or equal to this value. schema: type: string format: datetime example: '2024-01-01T00:00:00' fm_analytics_query_filter_date__lte: in: query name: filter_date__lte required: false description: > Return only feedback results whose date is less than or equal to this value. schema: type: string format: datetime example: '2024-03-31T23:59:59' query_survey__in: in: query name: survey__in required: false description: >- Filter results to the specified survey (feedback form) IDs (comma-separated). schema: type: string example: 674d791c13c9d976e20001b1,674d791c13c9d976e20001b2 query_survey_field__in: in: query name: survey_field__in required: false description: Filter results to the specified form field IDs (comma-separated). schema: type: string query_survey_field_type__in: in: query name: survey_field_type__in required: false description: >- Filter results to the specified form field types (comma-separated, e.g. `CSAT,NPS`). schema: type: string example: CSAT,NPS query_result_nps_score__in: in: query name: result_nps_score__in required: false description: >- Filter results to the specified NPS scores (comma-separated integers, 0–10). schema: type: string example: 9,10 query_result_id__in: in: query name: result_id__in required: false description: Filter to specific feedback result IDs (comma-separated). schema: type: string query_verbatim_query: in: query name: verbatim_query required: false description: Full-text search within feedback comments and verbatim responses. schema: type: string query_issues__in: in: query name: issues__in required: false description: > Filter to results that have one of the specified data quality issues (comma-separated). - `deleted_business`: The associated business has been deleted - `missing_store_code`: The business is missing a store code schema: type: string enum: - deleted_business - missing_store_code query_issues__notin: in: query name: issues__notin required: false description: > Exclude results that have one of the specified data quality issues (comma-separated). - `deleted_business`: The associated business has been deleted - `missing_store_code`: The business is missing a store code schema: type: string enum: - deleted_business - missing_store_code query_metadata: in: query name: metadata required: false description: > When `true`, the response includes a `metadata` object containing full entity details (businesses, forms, users, groups, etc.) referenced by IDs in the `data` array. Useful for resolving IDs to display names without additional API calls. schema: type: boolean default: false query_download: in: query name: download required: false description: | When `true`, the response is an Excel file (`.xlsx`) instead of JSON. The `Content-Disposition` header contains the generated filename. schema: type: boolean default: false query_table_name: in: query name: table_name required: false description: > Custom label used as part of the generated Excel filename when `download=true`. Special characters are sanitised automatically. schema: type: string example: Q1-2024-CSAT fm_analytics_query_page: in: query name: page required: false description: Page number to retrieve (1-based). schema: type: integer default: 1 minimum: 1 fm_analytics_query_per_page: in: query name: per_page required: false description: Number of results per page. schema: type: integer minimum: 1 maximum: 1000 default: 100 schemas: FeedbackAnalyticsResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/FeedbackAnalyticsDataItem' description: >- Array of analytics rows. Each row contains metric values and dimension identifiers. metadata: $ref: '#/components/schemas/FeedbackAnalyticsMetadata' page: type: integer description: Current page number. example: 1 count: type: integer description: Total number of results matching the query. example: 42 max_page: type: integer nullable: true description: Total number of pages available. example: 5 FeedbackAnalyticsDataItem: type: object description: > One row of analytics data. Keys are the requested metric names and dimension serializer keys. Metric values are numeric; dimension values are strings (IDs) or dates. additionalProperties: true example: result.csat.score: 87.5 result.csat.avg_score: 4.2 result.csat.total_responses: 120 business_id: 59b2645db12ff60643ef832c date: '2024-01-01' FeedbackAnalyticsMetadata: type: object description: > Entity details referenced by IDs in the `data` array. Only present when `metadata=true` is passed in the request. Each key is a dimension name; its value is an array of the corresponding entities. properties: feedback_form: type: array items: $ref: '#/components/schemas/FeedbackFormSummary' description: Feedback forms referenced in the data. feedback_form_field: type: array items: $ref: '#/components/schemas/FeedbackFormFieldSummary' description: Form fields referenced in the data. business: type: array description: Businesses referenced in the data. items: type: object additionalProperties: true group: type: array description: Business groups referenced in the data. items: type: object additionalProperties: true group_section: type: array description: Group sections referenced in the data. items: type: object additionalProperties: true user: type: array description: Users referenced in the data. items: type: object additionalProperties: true result: type: array description: Individual feedback results referenced in the data. items: type: object additionalProperties: true FeedbackFormSummary: type: object description: Summary of a feedback form (survey). properties: id: type: string description: Unique identifier of the feedback form. example: 674d791c13c9d976e20001b1 display_name: type: string description: Human-readable name of the feedback form. example: Customer Satisfaction Q1 2024 FeedbackFormFieldSummary: type: object description: Summary of a form field. properties: id: type: string description: Unique identifier of the field. example: 674d791c13c9d976e20001c3 field_type: type: string description: Type of the field (e.g. CSAT, NPS, TEXT). example: CSAT field_label: type: string description: Display label of the field. example: How satisfied are you? form_id: type: string description: ID of the parent feedback form. example: 674d791c13c9d976e20001b1 form_display_name: type: string description: Display name of the parent feedback form. example: Customer Satisfaction Q1 2024 responses: '401': description: You are not authenticated content: application/json: schema: description: Error that occurs when you are not authenticated type: object properties: errors: type: object description: The detail of the error encountered properties: authentication: type: string default: User not authenticated '403': description: | You are not allowed to perform this action content: application/json: schema: description: > Error that occurs when you are authenticated but you are trying to perform an action you are not allowed to perform type: object properties: errors: type: object description: The detail of the error encountered properties: authorization: type: string default: Operation not allowed securitySchemes: ApiKeyAuth: description: > The authentication system on Partoo API is using API Key that should be put in the header of the request (the name of the header is `x-APIKey`). An api_key is linked to a user. This user's role will give you different access level to the API features. type: apiKey in: header name: x-APIKey ````