How do I retrieve Matomo AI traffic reports through its API?

Definition: Matomo's Reporting API retrieves analytics reports through HTTP requests. Referrers.getAIAssistants returns AI referral reports for a website, period and date, with segment restricting the included visits.

Key facts

• As of October 2026, Matomo's Reporting API reference lists Referrers.getAIAssistants for referrals and AIAgents.get for agent traffic.
• Matomo's terminology guide defines the AI Assistant acquisition channel as visitors referred through recognised assistant domains, using referrer information.
• Matomo's segmentation reference lists ai as a referrerType value.
• Matomo's Metadata API documentation identifies API.getReportMetadata as the method for listing report functions.

Which method retrieves the report?

A JSON request for yesterday's assistant referrals matches Matomo's API reference:

curl -X POST "$MATOMO_URL/index.php" \
  --data-urlencode 'module=API' \
  --data-urlencode 'method=Referrers.getAIAssistants' \
  --data-urlencode "idSite=$MATOMO_SITE_ID" \
  --data-urlencode 'period=day' \
  --data-urlencode 'date=yesterday' \
  --data-urlencode 'format=json' \
  --data-urlencode "token_auth=$MATOMO_TOKEN"

The variables supply the installation URL, website ID and token. The reference recommends POST-only tokens with token_auth in the request body.

For report selection, the Metadata API lists available report functions through API.getReportMetadata. For labelled output, API.getProcessedReport returns report metadata, translated column names and reportData; the underlying report is selected with apiModule and apiAction.

How does segmentation isolate assistant visits?

A segment defines the subset of visits used to calculate a report. Matomo's segmentation reference documents == for equality and ; for AND. The AI channel condition is:

referrerType==ai

Matomo's public demo response includes this segment for its ChatGPT row:

referrerType==ai;referrerName==ChatGPT

The expression can be supplied as the segment parameter to a report accepting segmentation. The segmentation reference requires URL encoding for segment values. A comma expresses OR, which takes precedence over AND when both occur.

Matomo's AI traffic reporting guide states that the AI Assistant channel applies to data collected after the channel update. Historical visits retain their original channels, while the dedicated assistant report may show past data through internal filtering of known AI referrers.

How do date and period affect the result?

Matomo's date parameter documentation uses the website's time zone. date accepts YYYY-MM-DD, today and yesterday; period=month selects the month containing that date.

A daily series including today uses:

period=day&date=last10

The same interval aggregated into a range report uses:

period=range&date=last10

lastX includes the current period; previousX selects preceding periods. An explicit interval uses date=YYYY-MM-DD,YYYY-MM-DD, with period=range returning an aggregate for that interval.

Related terms

• Where do I find AI assistant traffic in Matomo?
• How do I create a Matomo segment for one AI assistant?
• How do I authenticate an automated Matomo report export?

FAQ

Which method provides visit totals for a segment?

You can use VisitsSummary.get, which Matomo's Metadata API guide describes as returning main metrics for a specified website. Its examples include visits and unique visitors.

Why can a referral report miss an assistant visit?

Matomo's terminology guide states that assistant referral attribution requires referrer information. If that information is absent, the visit cannot be attributed through this signal.

Sources

1. Matomo, "Reporting API Reference", undated
2. Matomo, "What are AI Assistants in Matomo", undated
3. Matomo, "Segmentation in the API", undated
4. Matomo, "Report Metadata API Methods", undated
5. Matomo, "Public demo: Referrers.getAIAssistants JSON response", undated
6. Matomo, "How to track and analyse traffic from AI Assistants (like ChatGPT) in Matomo reports", undated

---

Check how a page reads to answer engines. Open the GEO score analyzer