Matomo Tracking API (matomo.php entrypoint)

openapi: 3.2.0
info:
  title: Matomo Reporting Index.php Matomo.php API
  version: v1
  description: 'Programmatic access to Matomo analytics reports. All Reporting API calls

    are dispatched through a single `/index.php` entrypoint by supplying

    `module=API` and a `method=Module.MethodName` query parameter. The API

    exposes 200+ methods across modules like VisitsSummary, Actions,

    Referrers, UserCountry, DevicesDetection, and Goals.

    '
  contact:
    name: Matomo Developer Documentation
    url: https://developer.matomo.org/api-reference/reporting-api
servers:
- url: https://{matomo_host}
  description: Your Matomo instance (self-hosted or Matomo Cloud)
  variables:
    matomo_host:
      default: demo.matomo.cloud
security:
- TokenAuth: []
tags:
- name: Matomo.php
paths:
  /matomo.php:
    get:
      summary: Submit a single tracking request (querystring)
      operationId: trackEventGet
      description: 'Records a single pageview, event, content interaction, search, or

        ecommerce action by passing tracking parameters in the URL

        querystring. `idsite` and `rec=1` are required.

        '
      parameters:
      - $ref: '#/components/parameters/IdSite'
      - $ref: '#/components/parameters/Rec'
      - $ref: '#/components/parameters/ActionName'
      - $ref: '#/components/parameters/Url'
      - $ref: '#/components/parameters/VisitorId'
      - $ref: '#/components/parameters/Rand'
      - $ref: '#/components/parameters/ApiV'
      - $ref: '#/components/parameters/UrlRef'
      - $ref: '#/components/parameters/Res'
      - $ref: '#/components/parameters/Cookie'
      - $ref: '#/components/parameters/UserAgent'
      - $ref: '#/components/parameters/UaData'
      - $ref: '#/components/parameters/Lang'
      - $ref: '#/components/parameters/Uid'
      - $ref: '#/components/parameters/Cid'
      - $ref: '#/components/parameters/NewVisit'
      - $ref: '#/components/parameters/Link'
      - $ref: '#/components/parameters/Download'
      - $ref: '#/components/parameters/Search'
      - $ref: '#/components/parameters/SearchCat'
      - $ref: '#/components/parameters/SearchCount'
      - $ref: '#/components/parameters/PvId'
      - $ref: '#/components/parameters/IdGoal'
      - $ref: '#/components/parameters/Revenue'
      - $ref: '#/components/parameters/Ec'
      - $ref: '#/components/parameters/EventCategory'
      - $ref: '#/components/parameters/EventAction'
      - $ref: '#/components/parameters/EventName'
      - $ref: '#/components/parameters/EventValue'
      - $ref: '#/components/parameters/ContentName'
      - $ref: '#/components/parameters/ContentPiece'
      - $ref: '#/components/parameters/ContentTarget'
      - $ref: '#/components/parameters/ContentInteraction'
      - $ref: '#/components/parameters/EcId'
      - $ref: '#/components/parameters/EcItems'
      - $ref: '#/components/parameters/EcSt'
      - $ref: '#/components/parameters/EcTx'
      - $ref: '#/components/parameters/EcSh'
      - $ref: '#/components/parameters/EcDt'
      - $ref: '#/components/parameters/TokenAuth'
      - $ref: '#/components/parameters/Cip'
      - $ref: '#/components/parameters/Cdt'
      - $ref: '#/components/parameters/Country'
      - $ref: '#/components/parameters/Region'
      - $ref: '#/components/parameters/City'
      - $ref: '#/components/parameters/Lat'
      - $ref: '#/components/parameters/Long'
      - $ref: '#/components/parameters/SendImage'
      - $ref: '#/components/parameters/Ping'
      - $ref: '#/components/parameters/QueuedTracking'
      - $ref: '#/components/parameters/Bots'
      responses:
        '200':
          description: 'Default response is a 1x1 transparent GIF (204 if

            `send_image=0`). Errors surface in Matomo logs, not HTTP status.

            '
          content:
            image/gif: {}
      tags:
      - Matomo.php
    post:
      summary: Submit a single tracking request or a bulk batch
      operationId: trackEventPost
      description: 'POST may carry the same parameters as GET in a form-encoded body,

        or a JSON body containing a `requests` array for Bulk Tracking.

        Bulk tracking can include hundreds of requests in one HTTP call;

        requests should be sent in chronological order.

        '
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              description: Same parameter set as the GET variant.
          application/json:
            schema:
              $ref: '#/components/schemas/BulkRequest'
            examples:
              bulk:
                value:
                  requests:
                  - ?idsite=1&url=https://example.org&action_name=Test bulk log Pageview&rec=1
                  - ?idsite=1&url=https://example.net/test.htm&action_name=Another bulk page view&rec=1
                  token_auth: 33dc3f2536d3025974cccb4b4d2d98f4
      responses:
        '200':
          description: Tracking accepted.
      tags:
      - Matomo.php
components:
  parameters:
    EcItems:
      in: query
      name: ec_items
      schema:
        type: string
      description: JSON-encoded array of ecommerce line items.
    IdSite:
      in: query
      name: idsite
      required: true
      schema:
        type: integer
      description: ID of the website being tracked.
    Ec:
      in: query
      name: ec_id
      schema:
        type: string
      description: Unique String identifier for the ecommerce order.
    Rand:
      in: query
      name: rand
      schema:
        type: string
      description: Random value to avoid intermediary caching.
    EventName:
      in: query
      name: e_n
      schema:
        type: string
      description: Event name.
    Bots:
      in: query
      name: bots
      schema:
        type: integer
        enum:
        - 0
        - 1
      description: Set to 1 to record requests from known bots.
    Cookie:
      in: query
      name: cookie
      schema:
        type: integer
        enum:
        - 0
        - 1
      description: Whether the visitor's browser supports cookies.
    Rec:
      in: query
      name: rec
      required: true
      schema:
        type: integer
        enum:
        - 1
      description: Must be set to 1 to record the request.
    EcTx:
      in: query
      name: ec_tx
      schema:
        type: number
      description: Tax amount of the order.
    ContentName:
      in: query
      name: c_n
      schema:
        type: string
      description: Name of the content block.
    VisitorId:
      in: query
      name: _id
      schema:
        type: string
        minLength: 16
        maxLength: 16
      description: 16 character unique visitor ID (hex).
    Long:
      in: query
      name: long
      schema:
        type: number
      description: Override visitor longitude (requires token_auth).
    EventValue:
      in: query
      name: e_v
      schema:
        type: number
      description: Event numeric value.
    EcId:
      in: query
      name: ec_id
      schema:
        type: string
      description: Unique string identifier for the ecommerce order.
    SearchCat:
      in: query
      name: search_cat
      schema:
        type: string
      description: Specified search category.
    TokenAuth:
      in: query
      name: token_auth
      schema:
        type: string
      description: 'Auth token. Required for parameters that override server-side

        values (cip, cdt > 24h, country/region/city/lat/long, cid).

        '
    EcDt:
      in: query
      name: ec_dt
      schema:
        type: number
      description: Discount offered on the order.
    Revenue:
      in: query
      name: revenue
      schema:
        type: number
      description: Monetary value generated as revenue.
    UserAgent:
      in: query
      name: ua
      schema:
        type: string
      description: Override the User-Agent HTTP header.
    ApiV:
      in: query
      name: apiv
      schema:
        type: integer
        enum:
        - 1
      description: API version, currently 1.
    NewVisit:
      in: query
      name: new_visit
      schema:
        type: integer
        enum:
        - 0
        - 1
      description: Force a new visit to be created for this action.
    ContentPiece:
      in: query
      name: c_p
      schema:
        type: string
      description: Actual content piece (text or media URL).
    Cip:
      in: query
      name: cip
      schema:
        type: string
      description: Override the visitor IP (requires token_auth).
    Cdt:
      in: query
      name: cdt
      schema:
        type: string
      description: Override datetime of the request (UTC, requires token_auth if older than 24h).
    Cid:
      in: query
      name: cid
      schema:
        type: string
        minLength: 16
        maxLength: 16
      description: 16 character visitor ID override (requires token_auth).
    QueuedTracking:
      in: query
      name: queuedtracking
      schema:
        type: integer
        enum:
        - 0
        - 1
      description: Bypass the Queued Tracking plugin for this request.
    UaData:
      in: query
      name: uadata
      schema:
        type: string
      description: JSON-encoded Client Hints.
    Download:
      in: query
      name: download
      schema:
        type: string
        format: uri
      description: URL of a downloaded file.
    EcSh:
      in: query
      name: ec_sh
      schema:
        type: number
      description: Shipping cost of the order.
    Ping:
      in: query
      name: ping
      schema:
        type: integer
        enum:
        - 0
        - 1
      description: Heartbeat ping; updates total_time on an existing visit.
    EventAction:
      in: query
      name: e_a
      schema:
        type: string
      description: Event action.
    City:
      in: query
      name: city
      schema:
        type: string
      description: Override visitor city (requires token_auth).
    UrlRef:
      in: query
      name: urlref
      schema:
        type: string
        format: uri
      description: Full HTTP Referrer URL.
    EcSt:
      in: query
      name: ec_st
      schema:
        type: number
      description: Sub-total of the order, excluding shipping.
    SearchCount:
      in: query
      name: search_count
      schema:
        type: integer
      description: Number of search results displayed.
    Search:
      in: query
      name: search
      schema:
        type: string
      description: Site search query.
    PvId:
      in: query
      name: pv_id
      schema:
        type: string
        minLength: 6
        maxLength: 6
      description: 6 character unique ID for the pageview.
    EventCategory:
      in: query
      name: e_c
      schema:
        type: string
      description: Event category.
    Lat:
      in: query
      name: lat
      schema:
        type: number
      description: Override visitor latitude (requires token_auth).
    Region:
      in: query
      name: region
      schema:
        type: string
      description: Override visitor region code (requires token_auth).
    Url:
      in: query
      name: url
      schema:
        type: string
        format: uri
      description: Full URL for the current action.
    ContentTarget:
      in: query
      name: c_t
      schema:
        type: string
      description: Target of the content interaction (URL).
    SendImage:
      in: query
      name: send_image
      schema:
        type: integer
        enum:
        - 0
        - 1
      description: If 0, return HTTP 204 instead of the 1x1 GIF.
    IdGoal:
      in: query
      name: idgoal
      schema:
        type: integer
      description: Goal ID for conversion tracking.
    Uid:
      in: query
      name: uid
      schema:
        type: string
      description: User ID string for the logged-in user.
    Res:
      in: query
      name: res
      schema:
        type: string
      description: Screen resolution, e.g. 1280x1024.
    Link:
      in: query
      name: link
      schema:
        type: string
        format: uri
      description: External URL clicked by the user (outlink).
    ContentInteraction:
      in: query
      name: c_i
      schema:
        type: string
      description: Type of content interaction (e.g. click).
    Lang:
      in: query
      name: lang
      schema:
        type: string
      description: Accept-Language HTTP header override.
    ActionName:
      in: query
      name: action_name
      schema:
        type: string
      description: Title of the action being tracked (page title).
    Country:
      in: query
      name: country
      schema:
        type: string
      description: Override visitor country code (requires token_auth).
  schemas:
    BulkRequest:
      type: object
      required:
      - requests
      properties:
        requests:
          type: array
          description: 'Array of URL-encoded querystrings, each beginning with `?` and

            containing the same parameters accepted by `/matomo.php`.

            '
          items:
            type: string
        token_auth:
          type: string
          description: 'Optional auth token applied to all sub-requests. Required when

            any sub-request uses parameters that need authentication.

            '
  securitySchemes:
    TokenAuth:
      type: apiKey
      in: query
      name: token_auth
      description: 'Matomo auth token created in Administration > Personal > Security >

        Auth tokens. May be passed as a query parameter or, preferably, in

        the POST body.

        '