openapi: 3.1.0
info:
  title: Matomo Tracking API
  version: v1
  description: |
    The Matomo Tracking HTTP API records visits, pageviews, events, content
    interactions, site searches, ecommerce transactions, and custom dimensions
    from any client or server. All single-event requests hit the same
    `/matomo.php` endpoint and accept either GET (querystring) or POST
    (form-encoded body). A POST variant accepts a JSON `requests` array for
    Bulk Tracking, allowing many events to be submitted in one HTTP call.

    This specification reflects only parameters that are publicly documented
    at https://developer.matomo.org/api-reference/tracking-api. Some
    parameters require an authenticated `token_auth` (for example overriding
    IP, country, datetime, or visitor ID server-side).
  contact:
    name: Matomo Developer Documentation
    url: https://developer.matomo.org/api-reference/tracking-api
servers:
  - url: https://{matomo_host}
    description: Your Matomo instance (self-hosted or Matomo Cloud)
    variables:
      matomo_host:
        default: demo.matomo.cloud
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: {}
    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.
components:
  securitySchemes:
    TokenAuth:
      type: apiKey
      in: query
      name: token_auth
      description: |
        Auth token. Required when overriding visitor IP (`cip`), datetime
        (`cdt` older than 24h), geolocation, or visitor ID server-side, and
        for bulk tracking when any sub-request needs 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.
  parameters:
    IdSite:
      in: query
      name: idsite
      required: true
      schema: { type: integer }
      description: ID of the website being tracked.
    Rec:
      in: query
      name: rec
      required: true
      schema: { type: integer, enum: [1] }
      description: Must be set to 1 to record the request.
    ActionName:
      in: query
      name: action_name
      schema: { type: string }
      description: Title of the action being tracked (page title).
    Url:
      in: query
      name: url
      schema: { type: string, format: uri }
      description: Full URL for the current action.
    VisitorId:
      in: query
      name: _id
      schema: { type: string, minLength: 16, maxLength: 16 }
      description: 16 character unique visitor ID (hex).
    Rand:
      in: query
      name: rand
      schema: { type: string }
      description: Random value to avoid intermediary caching.
    ApiV:
      in: query
      name: apiv
      schema: { type: integer, enum: [1] }
      description: API version, currently 1.
    UrlRef:
      in: query
      name: urlref
      schema: { type: string, format: uri }
      description: Full HTTP Referrer URL.
    Res:
      in: query
      name: res
      schema: { type: string }
      description: Screen resolution, e.g. 1280x1024.
    Cookie:
      in: query
      name: cookie
      schema: { type: integer, enum: [0, 1] }
      description: Whether the visitor's browser supports cookies.
    UserAgent:
      in: query
      name: ua
      schema: { type: string }
      description: Override the User-Agent HTTP header.
    UaData:
      in: query
      name: uadata
      schema: { type: string }
      description: JSON-encoded Client Hints.
    Lang:
      in: query
      name: lang
      schema: { type: string }
      description: Accept-Language HTTP header override.
    Uid:
      in: query
      name: uid
      schema: { type: string }
      description: User ID string for the logged-in user.
    Cid:
      in: query
      name: cid
      schema: { type: string, minLength: 16, maxLength: 16 }
      description: 16 character visitor ID override (requires token_auth).
    NewVisit:
      in: query
      name: new_visit
      schema: { type: integer, enum: [0, 1] }
      description: Force a new visit to be created for this action.
    Link:
      in: query
      name: link
      schema: { type: string, format: uri }
      description: External URL clicked by the user (outlink).
    Download:
      in: query
      name: download
      schema: { type: string, format: uri }
      description: URL of a downloaded file.
    Search:
      in: query
      name: search
      schema: { type: string }
      description: Site search query.
    SearchCat:
      in: query
      name: search_cat
      schema: { type: string }
      description: Specified search category.
    SearchCount:
      in: query
      name: search_count
      schema: { type: integer }
      description: Number of search results displayed.
    PvId:
      in: query
      name: pv_id
      schema: { type: string, minLength: 6, maxLength: 6 }
      description: 6 character unique ID for the pageview.
    IdGoal:
      in: query
      name: idgoal
      schema: { type: integer }
      description: Goal ID for conversion tracking.
    Revenue:
      in: query
      name: revenue
      schema: { type: number }
      description: Monetary value generated as revenue.
    Ec:
      in: query
      name: ec_id
      schema: { type: string }
      description: Unique String identifier for the ecommerce order.
    EventCategory:
      in: query
      name: e_c
      schema: { type: string }
      description: Event category.
    EventAction:
      in: query
      name: e_a
      schema: { type: string }
      description: Event action.
    EventName:
      in: query
      name: e_n
      schema: { type: string }
      description: Event name.
    EventValue:
      in: query
      name: e_v
      schema: { type: number }
      description: Event numeric value.
    ContentName:
      in: query
      name: c_n
      schema: { type: string }
      description: Name of the content block.
    ContentPiece:
      in: query
      name: c_p
      schema: { type: string }
      description: Actual content piece (text or media URL).
    ContentTarget:
      in: query
      name: c_t
      schema: { type: string }
      description: Target of the content interaction (URL).
    ContentInteraction:
      in: query
      name: c_i
      schema: { type: string }
      description: Type of content interaction (e.g. click).
    EcId:
      in: query
      name: ec_id
      schema: { type: string }
      description: Unique string identifier for the ecommerce order.
    EcItems:
      in: query
      name: ec_items
      schema: { type: string }
      description: JSON-encoded array of ecommerce line items.
    EcSt:
      in: query
      name: ec_st
      schema: { type: number }
      description: Sub-total of the order, excluding shipping.
    EcTx:
      in: query
      name: ec_tx
      schema: { type: number }
      description: Tax amount of the order.
    EcSh:
      in: query
      name: ec_sh
      schema: { type: number }
      description: Shipping cost of the order.
    EcDt:
      in: query
      name: ec_dt
      schema: { type: number }
      description: Discount offered on the order.
    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).
    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).
    Country:
      in: query
      name: country
      schema: { type: string }
      description: Override visitor country code (requires token_auth).
    Region:
      in: query
      name: region
      schema: { type: string }
      description: Override visitor region code (requires token_auth).
    City:
      in: query
      name: city
      schema: { type: string }
      description: Override visitor city (requires token_auth).
    Lat:
      in: query
      name: lat
      schema: { type: number }
      description: Override visitor latitude (requires token_auth).
    Long:
      in: query
      name: long
      schema: { type: number }
      description: Override visitor longitude (requires token_auth).
    SendImage:
      in: query
      name: send_image
      schema: { type: integer, enum: [0, 1] }
      description: If 0, return HTTP 204 instead of the 1x1 GIF.
    Ping:
      in: query
      name: ping
      schema: { type: integer, enum: [0, 1] }
      description: Heartbeat ping; updates total_time on an existing visit.
    QueuedTracking:
      in: query
      name: queuedtracking
      schema: { type: integer, enum: [0, 1] }
      description: Bypass the Queued Tracking plugin for this request.
    Bots:
      in: query
      name: bots
      schema: { type: integer, enum: [0, 1] }
      description: Set to 1 to record requests from known bots.