← Back

Connect Your Backend to Agent & LLM Analytics

Overview

Use the REST API to connect your website with a backend written in any programming language. Please contact us if you need help getting set up.

Step 1: Start Tracking Visits

In the endpoints where you serve your pages, make an HTTP request to the REST API for each incoming pageview request.

URL
URL https://api.knownagents.com/visits
HTTP Method POST
Headers
Authorization A bearer token with your project's access token (e.g. Bearer YOUR_ACCESS_TOKEN). You can get your project's access token by navigating to the Known Agents Projects page, opening your project, and opening its settings page.
Content-Type This needs to be set to application/json.
Body
Send either a single object or an array of objects. Large websites should use the batch method to reduce API overhead. Collect visits in memory and send them periodically, e.g., every few seconds or when you reach a maximum batch size.
request_path The URL path of the incoming pageview request.
request_method The HTTP method of the incoming pageview request (e.g. GET).
request_headers The HTTP headers of the incoming pageview request, as a key-value object. This should at least include user-agent, referer, and any IP-related headers (e.g., x-forwarded-for).
response_status_code Optional. The HTTP status code of the response (e.g. 200, 404).
response_duration_in_milliseconds Optional. The time taken to process the request and generate the response, in milliseconds.

Example

curl -X POST https://api.knownagents.com/visits \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '[
    {
        "request_path": "/pages/1234",
        "request_method": "GET",
        "request_headers": {
            "user-agent": "Mozilla/5.0...",
            "referer": "https://www.google.com",
            "x-forwarded-for": "203.0.113.42"
        },
        "response_status_code": 200,
        "response_duration_in_milliseconds": 45
    },
    {
        "request_path": "/about?foo=bar",
        "request_method": "GET",
        "request_headers": {
            "user-agent": "Mozilla/5.0...",
            "x-forwarded-for": "198.51.100.73"
        },
        "response_status_code": 200,
        "response_duration_in_milliseconds": 32
    }
]'

Tips

Step 2: Test Your Integration

If your website is correctly connected, you should see visits from a test agent in the realtime timeline within a few seconds.