Sending traffic data through the Server API

With the Server API, your web server reports every page view to KI Score via HTTP POST. Traffic Overview uses these reports to show which AI crawlers fetch your website and which visits come from AI sources such as ChatGPT. This article explains what to send and how to check that the data is arriving.

Prerequisites

• Your website has been added to KI Score.
• You or your development team can change server-side code, for example through middleware or a request hook. The integration page lists WordPress, Next.js, Laravel, Symfony, and custom systems as examples. For WordPress and Next.js 16, it has dedicated guides with code you can copy. For all other systems, you build the connection yourself.
• The report has to come from your server. KI Score does not offer a JavaScript snippet for the browser.

Copying the endpoint and tracking key

1. In the sidebar, select the website you want.
2. Open Einstellungen → Traffic-Tracking (Settings → Traffic tracking).
3. Under Verfügbare Integrationen (Available integrations), click the Server API card. The guide opens in a window.
4. Copy Dein Tracking-Endpoint (Your tracking endpoint) using Kopieren (Copy).
5. Copy the Universelles cURL-Beispiel (Universal cURL example) using Kopieren. It already contains your tracking key.

Always take the endpoint from this page instead of hard-coding a URL. It ends with your website’s site ID, an identifier made up of 32 hex characters.

Every report must include the tracking key in the X-Kiscore-Tracking-Secret header. If the header is missing or wrong, KI Score responds with status 401. The key is derived from the site ID and cannot be regenerated in the dashboard. Treat it like a password and use it only in server-side code. If it has become public anyway, contact support@kiscore.ai.

Note: The integration page also shows cards for Nuxt, TYPO3, WordPress, and Next.js. For what applies to them, see Are there plugins for Nuxt and TYPO3?

What data to send

For each page view, send a JSON body containing the values from your visitor’s actual request:

POST <Your tracking endpoint>
Content-Type: application/json
X-Kiscore-Tracking-Secret: <your tracking key>

{
  "user_agent": "<user agent of the request>",
  "referer": "<referrer of the request>",
  "url": "<full URL including the query string>",
  "ip": "<IP address of the request>",
  "title": "<page title>"
}

• user_agent, referer, url, and ip come from the incoming request.
• url must be complete, including the query string. Otherwise attribution through parameters such as utm_source=chatgpt.com is lost.
• title is optional.
• session_id and utm_source, utm_medium, utm_campaign, utm_term, and utm_content are optional as well. If you don’t send your own UTM fields, KI Score reads the UTM parameters from the URL.

If a field is too long, KI Score rejects the report with status 413. The limits are 1,024 bytes for user_agent, 2,048 bytes for referer and url, 64 bytes for ip, 512 bytes for title, and 255 bytes for session_id and each UTM field.

KI Score stores only detected AI crawlers and visits that arrive through an AI source. It does not store visitors’ IP addresses. As the website operator, you are responsible for informing your visitors about this tracking. Depending on your situation, you may need a data processing agreement.

Sending asynchronously so your pages stay fast

Send the report in a way that your website’s response doesn’t wait for KI Score, for example through a background job or a queue. Set a short timeout, and make sure your page is still delivered normally if the report fails.

Two limits apply to reports: 120 requests per minute per sending IP address and 600 requests per minute per website. Because all reports come from your server, the IP limit applies to your server as a whole. If a limit is exceeded, KI Score responds with status 429.

Checking that data arrives

KI Score answers an accepted report with {"status": "ok", "tracked": …}. tracked is true when KI Score detected an AI crawler in that request. For an ordinary page view it is false, even if the visit is counted as an AI referral. That is not an error.

1. In the sidebar, open KI-Traffic (AI traffic) → Traffic Overview.
2. Open the KI-Crawler (AI crawlers) tab. An AI crawler appears here after its next visit.
3. Open the KI-Verweise (AI referrals) tab. Visits from ChatGPT, Perplexity, and other AI sources appear here.

As long as no event has ever been stored, Traffic Overview shows the notice “Noch keine Traffic-Daten eingegangen” (no traffic data received yet) instead. If both tabs stay empty, check the selected time range and the status codes of your reports.