← Back

Track Visits With the Agent & LLM Analytics REST API

Overview

This guide shows you how to use the Agent & LLM Analytics REST API. Please contact us if you need help.

Request

Call this endpoint for every incoming network request to your website, including pageviews, REST calls, MCP calls, and agentic commerce calls for ACP and UCP. See the Cloudflare Worker guide for an example that populates all of the fields.

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 Set to application/json.
Body
Send either a single object or an array of objects with the fields below. High traffic websites should batch multiple events together and send them periodically (e.g. every 30 seconds).
Field Type Required Description
request_path string Yes The URL path of the incoming request.
request_method string Yes The HTTP method of the incoming request (e.g. GET, POST).
request_headers object Yes The HTTP headers of the incoming request, as a key-value object. This should at least include user-agent, any IP-related headers (e.g. x-forwarded-for), and referer when available.
response_status_code number No The HTTP status code of the response (e.g. 200, 404).
response_headers object No The HTTP headers of the response, as a key-value object. This should at least include content-type if available.
response_duration_in_milliseconds number No The time taken to process the request and generate the response, in milliseconds.
mcp_request_method string No The MCP mcp_request_body.method, if it exists.
mcp_request_tool_name string No The MCP mcp_request_body.params.name, if it exists.
mcp_request_client_info_name string No The MCP mcp_request_body.params.clientInfo.name, if it exists.
mcp_request_client_info_version string No The MCP mcp_request_body.params.clientInfo.version, if it exists.
mcp_response_result_is_error boolean No The MCP mcp_response_body.result.isError, if it exists.
mcp_response_error_code number No The MCP mcp_response_body.error.code, if it exists.
mcp_response_error_message string No The MCP mcp_response_body.error.message, if it exists.
acp_response_body object No The ACP response body, if it exists. For REST responses, pass the JSON response body. For MCP tool responses, pass mcp_response_body.result.
ucp_response_body object No The UCP response body, if it exists. For REST responses, pass the JSON response body. For MCP tool responses, pass mcp_response_body.result.structuredContent.

Tips

Example

curl -X POST https://api.knownagents.com/visits \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '[
    {
        "request_path": "/articles/1234",
        "request_method": "GET",
        "request_headers": { "...": "..." },
        "response_status_code": 200,
        "response_headers": { "...": "..." },
        "response_duration_in_milliseconds": 45
    },
    {
        "request_path": "/mcp",
        "request_method": "POST",
        "request_headers": { "...": "..." },
        "response_status_code": 200,
        "response_headers": { "...": "..." },
        "response_duration_in_milliseconds": 32,
        "mcp_request_method": "tools/call",
        "mcp_request_tool_name": "get_weather",
        "mcp_request_client_info_name": "Claude",
        "mcp_request_client_info_version": "1.0.0",
        "mcp_response_result_is_error": false
    },
    {
        "request_path": "/acp",
        "request_method": "POST",
        "request_headers": { "...": "..." },
        "response_status_code": 200,
        "response_headers": { "...": "..." },
        "response_duration_in_milliseconds": 38,
        "mcp_request_method": "tools/call",
        "mcp_request_tool_name": "complete_checkout_session",
        "mcp_request_client_info_name": "ChatGPT",
        "mcp_request_client_info_version": "1.0.0",
        "mcp_response_result_is_error": false,
        "acp_response_body": { "...": "..." }
    }
]'

Response

The endpoint returns 204 No Content when events are accepted.

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.