openapi: 3.2.0 info: title: Matomo Reporting API for plugin Insights API version: 1.0.0 description: Provides API methods for insight and mover/shaker comparisons between report periods. servers: - url: https://demo-proxy.innocraft.cloud/ description: Current Matomo instance security: - MatomoToken: [] tags: - name: Insights description: Provides API methods for insight and mover/shaker comparisons between report periods. paths: /index.php?module=API&method=Insights.canGenerateInsights: get: tags: - Insights description: Detects whether insights can be generated for this date/period combination or not. operationId: Insights.canGenerateInsights parameters: - $ref: '#/components/parameters/formatOptional' - name: date in: query description: The date or date range to process. 'YYYY-MM-DD', magic keywords (today, yesterday, lastWeek, lastMonth, lastYear), or date range (ie, 'YYYY-MM-DD,YYYY-MM-DD', lastX, previousX). required: true schema: type: string example: yesterday - name: period in: query description: The period to process, processes data for the period containing the specified date. required: true schema: type: string enum: - day - week - month - year - range example: day responses: '200': description: 'Whether a previous comparison period exists for the requested date/period combination. Example responses require Super User access. Use Try it out to see a live response.' content: text/xml: [] application/json: [] '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' default: $ref: '#/components/responses/DefaultError' /index.php?module=API&method=Insights.getInsightsOverview: get: tags: - Insights description: Generates insights for a set of reports. Plugins can add their own reports to be included in the insights overview by listening to the {@hook Insights.addReportToOverview} event. operationId: Insights.getInsightsOverview parameters: - $ref: '#/components/parameters/formatOptional' - name: idSite in: query description: The numeric ID of the website to query. required: true schema: type: integer example: 1 - name: period in: query description: The period to process, processes data for the period containing the specified date. required: true schema: type: string enum: - day - week - month - year - range example: day - name: date in: query description: The date or date range to process. 'YYYY-MM-DD', magic keywords (today, yesterday, lastWeek, lastMonth, lastYear), or date range (ie, 'YYYY-MM-DD,YYYY-MM-DD', lastX, previousX). required: true schema: type: string example: yesterday - name: segment in: query description: 'Custom segment to filter the report. Example: "referrerName==example.com" Supports AND (;) and OR (,) operators.' required: false schema: type: string responses: '200': description: 'Insight tables for every report included in the overview. Example responses require Super User access. Use Try it out to see a live response.' content: text/xml: [] application/json: [] application/vnd.ms-excel: [] '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' default: $ref: '#/components/responses/DefaultError' /index.php?module=API&method=Insights.getMoversAndShakersOverview: get: tags: - Insights description: Detects the movers and shakers for a set of reports. Plugins can add their own reports to be included in this overview by listening to the {@hook Insights.addReportToOverview} event. operationId: Insights.getMoversAndShakersOverview parameters: - $ref: '#/components/parameters/formatOptional' - name: idSite in: query description: The numeric ID of the website to query. required: true schema: type: integer example: 1 - name: period in: query description: The period to process, processes data for the period containing the specified date. required: true schema: type: string enum: - day - week - month - year - range example: day - name: date in: query description: The date or date range to process. 'YYYY-MM-DD', magic keywords (today, yesterday, lastWeek, lastMonth, lastYear), or date range (ie, 'YYYY-MM-DD,YYYY-MM-DD', lastX, previousX). required: true schema: type: string example: yesterday - name: segment in: query description: 'Custom segment to filter the report. Example: "referrerName==example.com" Supports AND (;) and OR (,) operators.' required: false schema: type: string responses: '200': description: 'Movers-and-shakers tables for every report included in the overview. Example responses require Super User access. Use Try it out to see a live response.' content: text/xml: [] application/json: [] application/vnd.ms-excel: [] '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' default: $ref: '#/components/responses/DefaultError' /index.php?module=API&method=Insights.getMoversAndShakers: get: tags: - Insights description: Detects the movers and shakers of a given date / report combination. A mover and shakers has an higher impact than other rows on average. For instance if a sites pageviews increase by 10% a page that increased by 40% at the same time contributed significantly more to the success than the average of 10%. operationId: Insights.getMoversAndShakers parameters: - $ref: '#/components/parameters/formatOptional' - name: idSite in: query description: The numeric ID of the website to query. required: true schema: type: integer example: 1 - name: period in: query description: The period to process, processes data for the period containing the specified date. required: true schema: type: string enum: - day - week - month - year - range example: day - name: date in: query description: The date or date range to process. 'YYYY-MM-DD', magic keywords (today, yesterday, lastWeek, lastMonth, lastYear), or date range (ie, 'YYYY-MM-DD,YYYY-MM-DD', lastX, previousX). required: true schema: type: string example: yesterday - name: reportUniqueId in: query description: Report identifier, for example `Actions_getPageUrls`. required: true schema: type: string example: VisitsSummary_get - name: segment in: query description: 'Custom segment to filter the report. Example: "referrerName==example.com" Supports AND (;) and OR (,) operators.' required: false schema: type: string - name: comparedToXPeriods in: query description: Number of past periods to compare against. required: false schema: type: integer default: 1 - name: limitIncreaser in: query description: Maximum number of positive movers to include. `0` excludes them. required: false schema: type: integer default: 4 - name: limitDecreaser in: query description: Maximum number of negative movers to include. `0` excludes them. required: false schema: type: integer default: 4 responses: '200': description: 'Movers-and-shakers rows for the requested report. Example responses require Super User access. Use Try it out to see a live response.' content: text/xml: [] application/json: [] application/vnd.ms-excel: [] '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' default: $ref: '#/components/responses/DefaultError' /index.php?module=API&method=Insights.getInsights: get: tags: - Insights description: Generates insights by comparing the report for a given date/period with a different date and calculating the difference. The API can exclude rows which growth is not good enough or did not have enough impact. operationId: Insights.getInsights parameters: - $ref: '#/components/parameters/formatOptional' - name: idSite in: query description: The numeric ID of the website to query. required: true schema: type: integer example: 1 - name: period in: query description: The period to process, processes data for the period containing the specified date. required: true schema: type: string enum: - day - week - month - year - range example: day - name: date in: query description: The date or date range to process. 'YYYY-MM-DD', magic keywords (today, yesterday, lastWeek, lastMonth, lastYear), or date range (ie, 'YYYY-MM-DD,YYYY-MM-DD', lastX, previousX). required: true schema: type: string example: yesterday - name: reportUniqueId in: query description: Report identifier, for example `Actions_getPageUrls`. required: true schema: type: string example: VisitsSummary_get - name: segment in: query description: 'Custom segment to filter the report. Example: "referrerName==example.com" Supports AND (;) and OR (,) operators.' required: false schema: type: string - name: limitIncreaser in: query description: Maximum number of positive movers to include. `0` excludes them. required: false schema: type: integer default: 5 - name: limitDecreaser in: query description: Maximum number of negative movers to include. `0` excludes them. required: false schema: type: integer default: 5 - name: filterBy in: query description: Optional filter for mover type. required: false schema: type: string default: '' enum: - '' - movers - new - disappeared - name: minImpactPercent in: query description: Minimum impact threshold in percent. required: false schema: type: integer default: 2 - name: minGrowthPercent in: query description: Minimum growth threshold in percent compared to the previous period. required: false schema: type: integer default: 20 - name: comparedToXPeriods in: query description: Number of past periods to compare against. required: false schema: type: integer default: 1 - name: orderBy in: query description: Row ordering mode. required: false schema: type: string default: absolute enum: - absolute - relative - importance responses: '200': description: 'Insight rows for the requested report. Example responses require Super User access. Use Try it out to see a live response.' content: text/xml: [] application/json: [] application/vnd.ms-excel: [] '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' default: $ref: '#/components/responses/DefaultError' components: responses: NotFound: description: Resource not found. content: text/plain: schema: type: string example: 'Error: The method is not available.' text/html: schema: type: string example: The method is not available. application/json: schema: $ref: '#/components/schemas/Error' application/xml: schema: $ref: '#/components/schemas/ErrorXml' ServerError: description: Unexpected server error. content: text/plain: schema: type: string example: 'Error: There was an error.' text/html: schema: type: string example: There was an error. application/json: schema: $ref: '#/components/schemas/Error' application/xml: schema: $ref: '#/components/schemas/ErrorXml' Unauthorized: description: Authentication failed or missing token. content: text/plain: schema: type: string example: 'Error: You must be logged in to access this functionality.' text/html: schema: type: string example: You must be logged in to access this functionality. application/json: schema: $ref: '#/components/schemas/Error' application/xml: schema: $ref: '#/components/schemas/ErrorXml' Forbidden: description: Authenticated but not allowed to access the resource. content: text/plain: schema: type: string example: 'Error: Not authorised.' text/html: schema: type: string example: Not authorised. application/json: schema: $ref: '#/components/schemas/Error' application/xml: schema: $ref: '#/components/schemas/ErrorXml' DefaultError: description: Default error response (any non-2xx). content: text/plain: schema: type: string example: 'Error: There was an error.' text/html: schema: type: string example: There was an error. application/json: schema: $ref: '#/components/schemas/Error' application/xml: schema: $ref: '#/components/schemas/ErrorXml' BadRequest: description: Bad request (validation or missing parameters). content: text/plain: schema: type: string example: 'Error: There was an error.' text/html: schema: type: string example: There was an error. application/json: schema: $ref: '#/components/schemas/Error' application/xml: schema: $ref: '#/components/schemas/ErrorXml' parameters: formatOptional: name: format in: query description: Response format. Defaults to `xml`. Use `original` to get the original PHP data structure. required: false schema: type: string default: xml enum: - xml - json - csv - tsv - html - rss - original schemas: ErrorXml: description: Generic Matomo error payload in XML. properties: error: properties: message: type: string xml: attribute: true example: There was an error type: object xml: name: error type: object xml: name: result Error: description: Generic Matomo error payload. required: - result - message properties: result: type: string example: error message: type: string example: There was an error code: type: integer type: object additionalProperties: true securitySchemes: MatomoToken: type: http description: Paste your token generated from Personal > Security. Swagger will send it as a Bearer token. scheme: bearer externalDocs: description: Matomo Reporting API developer page url: https://developer.matomo.org/api-reference/reporting-api/