VisitorInterest API lets you access visitor engagement distribution reports, including visits by pages viewed, visit duration, days since last visit, and visit count.
Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelistoverlay
GET/index.php?module=API&method=VisitorInterest.getNumberOfVisitsPerVisitDurationReport visits by visit duration · Visitor interest get number of visits per visit duration#
Ask an LLM
“How long do visitors typically stay on my site?”
“What share of visits last under 30 seconds?”
Tell an agent
Show the distribution of visit durations for site {idSite} for {period} {date}.
Group visits by time spent on site {idSite} on {date}.
GET/index.php?module=API&method=VisitorInterest.getNumberOfVisitsPerPageReport visits by pages viewed · Visitor interest get number of visits per page#
Ask an LLM
“How many pages do visitors usually look at per visit?”
“What portion of visits only view a single page?”
Tell an agent
Show the page-depth distribution for site {idSite} for {period} {date}.
Group visits by number of pages viewed on site {idSite} on {date}.
GET/index.php?module=API&method=VisitorInterest.getNumberOfVisitsByDaysSinceLastReport visits by days since previous visit · Visitor interest get number of visits by days since last#
Ask an LLM
“How many days pass before returning visitors come back?”
“Do my returning visitors come back within a week?”
Tell an agent
Show visits grouped by days since the previous visit for site {idSite} for {period} {date}.
Break down return gaps in days for site {idSite} on {date}.
GET/index.php?module=API&method=VisitorInterest.getNumberOfVisitsByVisitCountReport visits by lifetime visit count · Visitor interest get number of visits by visit count#
Ask an LLM
“How many of my visitors are on their first, second or tenth visit?”
“What does visitor loyalty look like by total number of visits?”
Tell an agent
Show visits grouped by lifetime visit count for site {idSite} for {period} {date}.
Break down loyalty by visit number for site {idSite} on {date}.
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we
store it to create your key and to recognise you if you sign in with another
provider. See our Privacy Policy and
Terms.
openapi: 3.2.0
info:
title: Matomo Reporting API for plugin Visitor Interest API
version: 1.0.0
description: VisitorInterest API lets you access visitor engagement distribution reports, including visits by pages viewed, visit duration, days since last visit, and visit count.
servers:
- url: https://demo-proxy.innocraft.cloud/
description: Current Matomo instance
security:
- MatomoToken: []
tags:
- name: VisitorInterest
description: VisitorInterest API lets you access visitor engagement distribution reports, including visits by pages viewed, visit duration, days since last visit, and visit count.
paths:
/index.php?module=API&method=VisitorInterest.getNumberOfVisitsPerVisitDuration:
get:
tags:
- VisitorInterest
description: Returns visit duration distribution metrics for the requested site and period.
operationId: VisitorInterest.getNumberOfVisitsPerVisitDuration
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: 'Visit counts grouped by visit duration ranges.
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'
summary: Visitor interest get number of visits per visit duration
x-summary-source: derived
/index.php?module=API&method=VisitorInterest.getNumberOfVisitsPerPage:
get:
tags:
- VisitorInterest
description: Returns page-depth distribution metrics for the requested site and period.
operationId: VisitorInterest.getNumberOfVisitsPerPage
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: 'Visit counts grouped by pages-per-visit ranges.
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'
summary: Visitor interest get number of visits per page
x-summary-source: derived
/index.php?module=API&method=VisitorInterest.getNumberOfVisitsByDaysSinceLast:
get:
tags:
- VisitorInterest
description: Returns the distribution of visits by days since the previous visit.
operationId: VisitorInterest.getNumberOfVisitsByDaysSinceLast
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: 'Visit counts grouped by days since the last visit.
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'
summary: Visitor interest get number of visits by days since last
x-summary-source: derived
/index.php?module=API&method=VisitorInterest.getNumberOfVisitsByVisitCount:
get:
tags:
- VisitorInterest
description: Returns the distribution of visits by lifetime visit count.
operationId: VisitorInterest.getNumberOfVisitsByVisitCount
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: 'Visit counts grouped by visit count ranges.
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'
summary: Visitor interest get number of visits by visit count
x-summary-source: derived
components:
responses:
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'
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'
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'
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'
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'
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'
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
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
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/