← Back
Track Pageviews & API Calls With the REST API
Request
Call this endpoint for every pageview, MCP call, and agentic commerce interaction using ACP or UCP.
Endpoint
| HTTP Method | POST |
|---|---|
| URL | https://api.knownagents.com/visits |
| Availability | All plans |
Headers
| Header | Value |
|---|---|
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
| 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. MCP requires mcp-protocol-version; ACP requires api-version; UCP requires ucp-agent. |
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. |
metadata |
object |
No | Key-value pairs to associate with the event. Values can be strings, numbers, or booleans. |
MCP Fields (Optional)
| Field | Type | Required | Description |
|---|---|---|---|
mcp_request_method |
string |
No | The MCP mcp_request_body.method, if it exists. |
mcp_request_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. |
Agentic Commerce Fields (Optional)
| Field | Type | Required | Description |
|---|---|---|---|
acp_response_body |
object |
No | The ACP response body, if it exists. For REST, pass the parsed JSON response body. For MCP, pass mcp_response_body.result. |
ucp_response_body |
object |
No | The UCP response body, if it exists. For REST, pass the parsed JSON response body. For MCP, pass mcp_response_body.result. |
Tips
- Add this in middleware to track pageviews and supported interactions from a single place.
- Send analytics outside your page response path. Use a background task or queue when available, and never let analytics failures affect the response.
- Strip out any sensitive HTTP headers you don't want to send.
- Strip out any sensitive fields from ACP and UCP response bodies before sending them.
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
}
]'
Response
The endpoint returns 204 No Content when events are accepted.
Test Your Integration
- Navigate to the Projects page
- Select your project
- Click Settings
- Click Send a Test Visit
- Click Realtime
If your website is correctly connected, you should see visits from a test agent in the realtime timeline within a few seconds.