Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Matomo Reporting API for plugin Visits Summary API
version: 1.0.0
description: VisitsSummary API lets you access the core web analytics metrics (visits, unique visitors, count of actions (page views & downloads & clicks on outlinks), time on site, bounces and converted visits.
servers:
- url: https://demo-proxy.innocraft.cloud/
description: Current Matomo instance
security:
- MatomoToken: []
tags:
- name: VisitsSummary
description: VisitsSummary API lets you access the core web analytics metrics (visits, unique visitors, count of actions (page views & downloads & clicks on outlinks), time on site, bounces and converted visits.
paths:
/index.php?module=API&method=VisitsSummary.get:
get:
tags:
- VisitsSummary
description: Returns the VisitsSummary overview report for the requested period.
operationId: VisitsSummary.get
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: idSite
in: query
description: Website ID(s) to query. - Single site ID (e.g. 1) - Multiple site IDs (e.g. [1, 4, 5]) - Comma-separated list ("1,4,5") or "all"
required: true
schema:
oneOf:
- type: integer
example: 1
- type: string
example: '1'
- type: array
items:
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
- name: columns
in: query
description: Specific metrics to include, or `false` to return the default set.
required: false
schema:
oneOf:
- type: string
- type: array
items:
type: string
responses:
'200':
description: 'VisitsSummary metrics for the requested period.
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=VisitsSummary.getVisits:
get:
tags:
- VisitsSummary
description: Returns the number of visits in the requested period.
operationId: VisitsSummary.getVisits
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: idSite
in: query
description: Website ID(s) to query. - Single site ID (e.g. 1) - Multiple site IDs (e.g. [1, 4, 5]) - Comma-separated list ("1,4,5") or "all"
required: true
schema:
oneOf:
- type: integer
example: 1
- type: string
example: '1'
- type: array
items:
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: 'Numeric archive result containing the number of visits.
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=VisitsSummary.getUniqueVisitors:
get:
tags:
- VisitsSummary
description: Returns the number of unique visitors in the requested period.
operationId: VisitsSummary.getUniqueVisitors
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: idSite
in: query
description: Website ID(s) to query. - Single site ID (e.g. 1) - Multiple site IDs (e.g. [1, 4, 5]) - Comma-separated list ("1,4,5") or "all"
required: true
schema:
oneOf:
- type: integer
example: 1
- type: string
example: '1'
- type: array
items:
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: 'Numeric archive result containing the number of unique visitors.
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=VisitsSummary.getUsers:
get:
tags:
- VisitsSummary
description: Returns the number of users in the requested period.
operationId: VisitsSummary.getUsers
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: idSite
in: query
description: Website ID(s) to query. - Single site ID (e.g. 1) - Multiple site IDs (e.g. [1, 4, 5]) - Comma-separated list ("1,4,5") or "all"
required: true
schema:
oneOf:
- type: integer
example: 1
- type: string
example: '1'
- type: array
items:
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: 'Numeric archive result containing the number of users.
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=VisitsSummary.getActions:
get:
tags:
- VisitsSummary
description: Returns the number of actions in the requested period.
operationId: VisitsSummary.getActions
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: idSite
in: query
description: Website ID(s) to query. - Single site ID (e.g. 1) - Multiple site IDs (e.g. [1, 4, 5]) - Comma-separated list ("1,4,5") or "all"
required: true
schema:
oneOf:
- type: integer
example: 1
- type: string
example: '1'
- type: array
items:
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: 'Numeric archive result containing the number of actions.
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=VisitsSummary.getMaxActions:
get:
tags:
- VisitsSummary
description: Returns the maximum number of actions in a single visit for the requested period.
operationId: VisitsSummary.getMaxActions
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: idSite
in: query
description: Website ID(s) to query. - Single site ID (e.g. 1) - Multiple site IDs (e.g. [1, 4, 5]) - Comma-separated list ("1,4,5") or "all"
required: true
schema:
oneOf:
- type: integer
example: 1
- type: string
example: '1'
- type: array
items:
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: 'Numeric archive result containing the maximum actions value.
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=VisitsSummary.getBounceCount:
get:
tags:
- VisitsSummary
description: Returns the number of bounces in the requested period.
operationId: VisitsSummary.getBounceCount
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: idSite
in: query
description: Website ID(s) to query. - Single site ID (e.g. 1) - Multiple site IDs (e.g. [1, 4, 5]) - Comma-separated list ("1,4,5") or "all"
required: true
schema:
oneOf:
- type: integer
example: 1
- type: string
example: '1'
- type: array
items:
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: 'Numeric archive result containing the bounce count.
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=VisitsSummary.getVisitsConverted:
get:
tags:
- VisitsSummary
description: Returns the number of converted visits in the requested period.
operationId: VisitsSummary.getVisitsConverted
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: idSite
in: query
description: Website ID(s) to query. - Single site ID (e.g. 1) - Multiple site IDs (e.g. [1, 4, 5]) - Comma-separated list ("1,4,5") or "all"
required: true
schema:
oneOf:
- type: integer
example: 1
- type: string
example: '1'
- type: array
items:
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: 'Numeric archive result containing converted visits.
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=VisitsSummary.getSumVisitsLength:
get:
tags:
- VisitsSummary
description: Returns the total visit duration in seconds for the requested period.
operationId: VisitsSummary.getSumVisitsLength
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: idSite
in: query
description: Website ID(s) to query. - Single site ID (e.g. 1) - Multiple site IDs (e.g. [1, 4, 5]) - Comma-separated list ("1,4,5") or "all"
required: true
schema:
oneOf:
- type: integer
example: 1
- type: string
example: '1'
- type: array
items:
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: 'Numeric archive result containing total visit duration.
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=VisitsSummary.getSumVisitsLengthPretty:
get:
tags:
- VisitsSummary
description: Returns the total visit duration formatted as human-readable text.
operationId: VisitsSummary.getSumVisitsLengthPretty
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: idSite
in: query
description: Website ID(s) to query. - Single site ID (e.g. 1) - Multiple site IDs (e.g. [1, 4, 5]) - Comma-separated list ("1,4,5") or "all"
required: true
schema:
oneOf:
- type: integer
example: 1
- type: string
example: '1'
- type: array
items:
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: 'Numeric archive result containing Human-readable visit duration values.
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/