← Back

Query Project Analytics With the REST API

Request

Call this endpoint to query daily analytics for the project associated with the access token. Queries can include the previous 30 complete UTC days.

Endpoint

HTTP Method POST
URL https://api.knownagents.com/query
Availability Enterprise 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
metric string Yes The metric to query. See the supported metrics below.
start_date string No The first UTC date to include in YYYY-MM-DD format. Provide both dates or omit both to select the previous 30 complete days.
end_date string No The last UTC date to include in YYYY-MM-DD format, through yesterday. Provide both dates or omit both to select the previous 30 complete days.
group_by string[] No The dimensions to group daily values by.
filters object No Metric-specific filters. Array filters must contain at least one value.
filters.agent_ids string[] No The agent IDs to include. Find these in the Metadata section of signed-in Agent Directory pages.
filters.agent_tokens string[] No The agent tokens to include, such as GPTBot and ChatGPT-User. Find these on Agent Directory pages.
filters.agent_type_ids string[] No The agent type IDs to include. Find these in the Metadata section of signed-in Agent Directory pages.
filters.agent_type_names string[] No The agent types to include:
  • "AI Agent"
  • "AI Assistant"
  • "AI Coding Agent"
  • "AI Data Provider"
  • "AI Data Scraper"
  • "AI Search Crawler"
  • "Archiver"
  • "Developer Helper"
  • "Fetcher"
  • "Automated Agent"
  • "Intelligence Gatherer"
  • "Scraper"
  • "SEO Crawler"
  • "Search Engine Crawler"
  • "Security Scanner"
  • "Undocumented AI Agent"
  • "Uncategorized"
filters.operator_ids string[] No The operator IDs to include. Find these in the Metadata section of signed-in Agent Directory pages.
filters.operator_names string[] No The operator names to include, such as OpenAI. Find these on Agent Directory pages.
filters.primary_automation_signals string[] No The primary automation signals to include:
  • "known_agent_ip"
  • "inconsistency"
  • "non_browser"
  • "automated_browser"
  • "residential_proxy"
  • "vpn"
  • "cloud_service_provider"
filters.is_disallowed boolean No Whether to include agent pageviews that were disallowed by robots.txt.
filters.is_mcp boolean No Whether to include API calls that used MCP.
filters.is_spoofed boolean No Whether to include agent pageviews that failed authentication.
filters.paths string[] No The exact paths to include, such as /blog/my-article.
filters.path_prefixes string[] No The path prefixes to include, such as /blog/.
filters.commerce_protocols string[] No The commerce protocols to include:
  • "acp"
  • "ucp"
filters.referrer_ids string[] No The referrer IDs to include. Find these by grouping referral_pageviews by referrer_id.
filters.referrer_names string[] No The referrer names to include, such as ChatGPT and Perplexity.
series_limit number No The maximum number of grouped series to return, ranked by their total value across the date range. Defaults to 100 and cannot exceed 1000.

Supported Metrics

Metric Group By Filters
agent_pageviews agent_id, agent_token, agent_type_id, agent_type_name, operator_id, operator_name, path, country_code, authentication_result, is_disallowed, is_spoofed, http_status_code, ip agent_ids, agent_tokens, agent_type_ids, agent_type_names, operator_ids, operator_names, is_disallowed, is_spoofed, paths, path_prefixes
sessions agent_id, agent_token, agent_type_id, agent_type_name, operator_id, operator_name agent_ids, agent_tokens, agent_type_ids, agent_type_names, operator_ids, operator_names
api_calls agent_id, agent_token, agent_type_id, agent_type_name, operator_id, operator_name, request_name (MCP only), operation, is_mcp, commerce_protocol, http_status_code, response_error_code (MCP only) agent_ids, agent_tokens, agent_type_ids, agent_type_names, operator_ids, operator_names, is_mcp, commerce_protocols
agentic_commerce_revenue currency (required) None
automated_pageviews primary_automation_signal, user_agent, ip primary_automation_signals
referral_pageviews referrer_id, referrer_name, path, country_code paths, path_prefixes, referrer_ids, referrer_names

Example

curl -X POST https://api.knownagents.com/query \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
    "metric": "agent_pageviews",
    "group_by": ["agent_token"],
    "filters": {
        "agent_type_names": ["AI Assistant"],
        "is_spoofed": false
    },
    "series_limit": 10
}'

Response

The endpoint returns the selected metric, date range, groupings, and daily result rows in application/json format. Grouped results omit series with no matching activity across the entire date range. Returned series contain every date, with a value of 0 when that series had no matching activity on a date.

Example

{
    "project_id": "PROJECT_ID",
    "metric": "agent_pageviews",
    "start_date": "START_DATE",
    "end_date": "END_DATE",
    "group_by": ["agent_token"],
    "rows": [
        {
            "date": "END_DATE",
            "dimensions": {
                "agent_token": "GPTBot"
            },
            "value": 42
        }
    ]
}