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 Referrers API
version: 1.0.0
description: The Referrers API lets you access reports about websites, search engines, keywords, social networks, AI assistants, and campaigns used to access your website. For example, "getKeywords" returns all search engine keywords (with <a href='https://developer.matomo.org/api-reference/reporting-api#api-response-metric-definitions' rel='noreferrer' target='_blank'>general analytics metrics</a> for each keyword), "getWebsites" returns referrer websites (along with the full Referrer URL if the parameter &expanded=1 is set). "getReferrerType" returns the Referrer overview report. "getCampaigns" returns the list of all campaigns (and all campaign keywords if the parameter &expanded=1 is set). "getSocials" returns social network referrers, and "getAIAssistants" returns AI assistant referrers.
servers:
- url: https://demo-proxy.innocraft.cloud/
description: Current Matomo instance
security:
- MatomoToken: []
tags:
- name: Referrers
description: The Referrers API lets you access reports about websites, search engines, keywords, social networks, AI assistants, and campaigns used to access your website. For example, "getKeywords" returns all search engine keywords (with <a href='https://developer.matomo.org/api-reference/reporting-api#api-response-metric-definitions' rel='noreferrer' target='_blank'>general analytics metrics</a> for each keyword), "getWebsites" returns referrer websites (along with the full Referrer URL if the parameter &expanded=1 is set). "getReferrerType" returns the Referrer overview report. "getCampaigns" returns the list of all campaigns (and all campaign keywords if the parameter &expanded=1 is set). "getSocials" returns social network referrers, and "getAIAssistants" returns AI assistant referrers.
paths:
/index.php?module=API&method=Referrers.get:
get:
tags:
- Referrers
description: Returns the referrer overview report with distinct referrer counts and percentage metrics.
operationId: Referrers.get
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: idSite
in: query
description: The site ID to query.
required: true
schema:
oneOf:
- type: integer
example: 1
- type: string
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 columns to include, or `false` to return all columns.
required: false
schema:
oneOf:
- type: string
- type: array
items:
type: string
responses:
'200':
description: 'Referrer overview rows with summary counts and processed percentage metrics.
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=Referrers.getReferrerType:
get:
tags:
- Referrers
description: Returns a report describing visit information for each possible referrer type. The result is a datatable whose subtables are the reports for each parent row's referrer type.
operationId: Referrers.getReferrerType
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: idSite
in: query
description: The site ID to query.
required: true
schema:
oneOf:
- type: integer
example: 1
- type: string
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: typeReferrer
in: query
description: Deprecated referrer type filter to restrict the returned rows.
required: false
schema:
oneOf:
- type: integer
- type: string
- name: idSubtable
in: query
description: Referrer type ID to load directly instead of the overview report.
required: false
schema:
type: integer
- name: expanded
in: query
description: '`true` to load subtables eagerly, `false` to return only top-level rows.'
required: false
schema:
type: boolean
default: false
- name: _setReferrerTypeLabel
in: query
description: '`true` to replace referrer type IDs with human-readable labels.'
required: false
schema:
type: boolean
default: true
responses:
'200':
description: 'Report rows for each referrer type, or the selected referrer-type subreport.
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=Referrers.getAll:
get:
tags:
- Referrers
description: Returns a flattened report containing all referrer subtables merged into one table.
operationId: Referrers.getAll
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: idSite
in: query
description: The site ID to query.
required: true
schema:
oneOf:
- type: integer
example: 1
- type: string
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: 'Flattened referrer report with subtables merged into the main table.
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=Referrers.getKeywords:
get:
tags:
- Referrers
description: Returns search keywords that brought visits to the requested website.
operationId: Referrers.getKeywords
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: expanded
in: query
description: '`true` to load keyword subtables eagerly.'
required: false
schema:
type: boolean
default: false
- name: flat
in: query
description: '`true` to flatten subtables into the main table.'
required: false
schema:
type: boolean
default: false
responses:
'200':
description: 'Search keyword rows 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=Referrers.getSearchEnginesFromKeywordId:
get:
tags:
- Referrers
description: Returns the search engines associated with a specific keyword subtable.
operationId: Referrers.getSearchEnginesFromKeywordId
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: idSite
in: query
description: The site ID to query.
required: true
schema:
oneOf:
- type: integer
example: 1
- type: string
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: idSubtable
in: query
description: Keyword subtable ID to expand.
required: true
schema:
type: integer
example: 2
- 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: 'Search engine rows for the selected keyword.
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=Referrers.getSearchEngines:
get:
tags:
- Referrers
description: Returns search engines that referred visits to the requested website.
operationId: Referrers.getSearchEngines
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: expanded
in: query
description: '`true` to load keyword subtables eagerly.'
required: false
schema:
type: boolean
default: false
- name: flat
in: query
description: '`true` to flatten subtables into the main table.'
required: false
schema:
type: boolean
default: false
responses:
'200':
description: 'Search engine rows 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=Referrers.getKeywordsFromSearchEngineId:
get:
tags:
- Referrers
description: Returns keywords for a specific search engine subtable.
operationId: Referrers.getKeywordsFromSearchEngineId
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: idSite
in: query
description: The site ID to query.
required: true
schema:
oneOf:
- type: integer
example: 1
- type: string
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: idSubtable
in: query
description: Search engine subtable ID to expand.
required: true
schema:
type: integer
example: 2
- 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: 'Keyword rows for the selected search engine.
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=Referrers.getCampaigns:
get:
tags:
- Referrers
description: Returns campaigns that referred visits to the requested website.
operationId: Referrers.getCampaigns
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: expanded
in: query
description: '`true` to load campaign keyword subtables eagerly.'
required: false
schema:
type: boolean
default: false
responses:
'200':
description: 'Campaign rows 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=Referrers.getKeywordsFromCampaignId:
get:
tags:
- Referrers
description: Returns campaign keywords for a specific campaign subtable.
operationId: Referrers.getKeywordsFromCampaignId
parameters:
- $ref: '#/components/parameters/formatOptional'
- name: idSite
in: query
description: The site ID to query.
required: true
schema:
oneOf:
- type: integer
example: 1
- type: string
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: idSubtable
in: query
description: Campaign subtable ID to expand.
required: true
schema:
type: integer
example: 2
- 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: 'Campaign keyword rows for the selected campaign.
Example responses require Super User access. Use Try it out to see a live response.'
'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=Referrers.getWebsites:
get:
tags:
- Referrers
description: Returns referring websites for the requested website.
operationId: Referrers.getWebsites
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: expanded
in: query
description: '`true` to load URL subtables eagerly.'
required: false
schema:
type: boolean
default: false
- name: flat
in: query
description: '`true` to flatten subtables into the main table.'
required: false
schema:
type: boolean
default: false
responses:
'200':
description: 'Referring website rows 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=Referrers.getUrlsFromWebsiteId:
get:
tags:
- Referrers
description: Returns individual referrer URLs for a specific website subtable.
operationId: Referrers.getUrlsFromWebsiteId
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: idSubtable
in: query
description: Website subtable ID to expand.
required: true
schema:
type: integer
example: 2
- 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: 'Referrer URL rows for the selected website.
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=Referrers.getSocials:
get:
tags:
- Referrers
description: Returns report comparing the number of visits and related metrics for social network referrers.
operationId: Referrers.getSocials
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: expanded
in: query
description: '`true` to load URL subtables eagerly.'
required: false
schema:
type: boolean
default: false
- name: flat
in: query
description: '`true` to flatten subtables into the main table.'
required: false
schema:
type: boolean
default: false
responses:
'200':
description: 'Social network referrer rows 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/Default
# --- truncated at 32 KB (63 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/matomo/refs/heads/main/openapi/matomo-referrers-api-openapi.yml