Instrument Microsoft Web IQ usage

This guide explains how to implement telemetry when using Web IQ APIs to log grounding content usage.

Overview

Web IQ APIs can be instrumented to include telemetry fields in responses, enabling your application to log user interaction metrics through HTTP requests.

Supported telemetry scenarios:

  • LLM usage: Log which search results a Large Language Model (LLM) references when creating its response.
  • End user clicks: Log which citations a user clicks on after being presented with a summarization and citations by the LLM.

Enabling Instrumentation

To log events, instrumentation must be enabled in your Web IQ APIs profile. Contact your Microsoft contact to configure this.

Response

After enabling instrumentation, API responses will include telemetry fields:

{
  "webResults": [
    {
      "...": "...",
      "instrumentationSuffix": "DevEx,1000"
    }
  ],
  "instrumentationClickBase": "https://api.microsoft.ai/api/ping?IG=some-impression-id&CID=some-client-id&ID=",
  "instrumentationCitationBase": "https://api.microsoft.ai/api/ping/llmLog?IG=some-impression-id&CID=some-client-id&Type=Event.ClientInst&DATA=",
  "traceId": "some-trace-id"
}

Field Descriptions

Field Description
instrumentationClickBase Base URL for reporting end-user clicks. IG (Impression GUID) and CID (Client ID) are prepopulated. ID must be appended with instrumentationSuffix manually.
instrumentationCitationBase Base URL for reporting LLM usage. Includes IG and CID. Type must be "Event.ClientInst". DATA is a URL-encoded JSON array of events.
instrumentationSuffix Unique identifier per result used for logging (e.g., DevEx,1000).
clickUrl If redirection is enabled, each result includes clickUrl, a redirect URL that forwards the end user to the original destination URL. With clickUrl, you do NOT need to manually log click events, but you still need to log LLM usage manually.

Note

When redirection is enabled in the profile, instrumentationClickBase will not be included in the response.

The following example shows a Web IQ API response when both instrumentation pings and URL redirection are enabled.

{
  "webResults": [
    {
      "url": "original-destination-link",
      "clickUrl": "encoded-redirection-link",
      "instrumentationSuffix": "DevEx,1000"
    }
  ],
  "instrumentationCitationBase": "https://api.microsoft.ai/api/ping/llmLog?IG=some-impression-id&CID=some-client-id&Type=Event.ClientInst&DATA=",
  "traceId": "some-trace-id"
}

Example Implementation

Request

Endpoint: POST https://api.microsoft.ai/v3/search/web

Sample Request:

curl -X POST "https://api.microsoft.ai/v3/search/web" \
  -H "host: api.microsoft.ai" \
  -H "x-apikey: <Your API key>" \
  -H "content-type: application/json" \
  -d '{
    "query": "webiq",
    "maxResults": 10,
    "language": "en",
    "region": "US",
    "maxLength": 3000,
    "contentFormat": "passage"
  }'

Response (Simplified)

{
  "webResults": [
    {
      "title": "Microsoft Web IQ",
      "url": "https://www.microsoft.com/en-us/webiq",
      "content": "...",
      "crawledAt": "2026-06-17T22:29:00.0000000Z",
      "language": "en",
      "isAdult": false,
      "instrumentationSuffix": "DevEx,1000"
    },
    {
      "title": "WebIQ - The Web HMI System for Professional HMIs",
      "url": "https://www.smart-hmi.com/",
      "content": "...",
      "crawledAt": "2026-06-16T01:17:00.0000000Z",
      "language": "en",
      "isAdult": false,
      "instrumentationSuffix": "DevEx,1001"
    }
  ],
  "instrumentationClickBase": "https://api.microsoft.ai/api/ping?IG=some-impression-id&CID=some-client-id&ID=",
  "instrumentationCitationBase": "https://api.microsoft.ai/api/ping/llmLog?IG=some-impression-id&CID=some-client-id&Type=Event.ClientInst&DATA=",
  "traceId": "some-trace-id"
}

Telemetry Workflow

Step 1: Provide Citations

Include citations in the LLM response to the user.

Step 2: Log LLM Usage

Build an array of objects with these fields:

Field Value
T subtype that represents the category of information. It should always be "CI.Info"
FID feature ID. It should always be "LLM"
Name name of the event for further information for classification. (e.g. "citation")
AppNS Prefix of instrumentationSuffix (e.g., "DevEx")
K Suffix value (e.g., "1000")

Example payload:

[
  {
    "T": "CI.Info",
    "FID": "LLM",
    "Name": "citation",
    "AppNS": "DevEx",
    "K": "1000"
  },
  {
    "T": "CI.Info",
    "FID": "LLM",
    "Name": "citation",
    "AppNS": "DevEx",
    "K": "1001"
  }
]

URL-encode the array:

var encoded_array = encodeURIComponent(JSON.stringify(data_array));

and send via:

Endpoint: GET https://api.microsoft.ai/api/ping/llmLog?IG=some-impression-id&CID=some-client-id&Type=Event.ClientInst&DATA=<encoded_array>

Step 3: Log User Clicks

When a user clicks a citation, send:

Endpoint: GET https://api.microsoft.ai/api/ping?IG=some-impression-id&CID=some-client-id&ID=DevEx,1001

  • Last updated on