← 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 Pageviews and API Calls

In the endpoints where you serve your pages or APIs, make an HTTP request to the REST API with information about incoming requests.

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).
Include these fields for all requests:
request_path The URL path of the incoming request.
request_method The HTTP method of the incoming request (e.g. GET, POST).
request_headers 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 Optional. The HTTP status code of the response (e.g. 200, 404).
response_headers Optional. The HTTP headers of the response, as a key-value object. This should at least include content-type if available.
response_duration_in_milliseconds Optional. The time taken to process the request and generate the response, in milliseconds.
Include these fields for MCP requests:
mcp_request_method Optional. The MCP mcp_request_body.method, if it exists.
mcp_request_tool_name Optional. The MCP mcp_request_body.params.name, if it exists.
mcp_request_client_info_name Optional. The MCP mcp_request_body.params.clientInfo.name, if it exists.
mcp_request_client_info_version Optional. The MCP mcp_request_body.params.clientInfo.version, if it exists.
mcp_response_result_is_error Optional. The MCP mcp_response_body.result.isError, if it exists.
mcp_response_error_code Optional. The MCP mcp_response_body.error.code, if it exists.
mcp_response_error_message Optional. The MCP mcp_response_body.error.message, if it exists.
Include these fields for ACP requests:
acp_response_currency Optional. The ACP response currency, if it exists. For REST responses, pull this from response_body.currency. For MCP tool responses, pull this from mcp_response_body.result.structuredContent.currency.
acp_response_total_amount Optional. The ACP response totals[].amount where totals[].type is "total", if it exists. For REST responses, pull this from response_body.totals[].amount. For MCP tool responses, pull this from mcp_response_body.result.structuredContent.totals[].amount.
Include these fields for UCP requests:
ucp_response_currency Optional. The UCP response currency, if it exists. For REST responses, pull this from response_body.currency. For MCP tool responses, pull this from mcp_response_body.result.structuredContent.currency.
ucp_response_total_amount Optional. The UCP response totals[].amount where totals[].type is "total", if it exists. For REST responses, pull this from response_body.totals[].amount. For MCP tool responses, pull this from mcp_response_body.result.structuredContent.totals[].amount.

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_currency": "USD",
        "acp_response_total_amount": 26550
    }
]'

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.