{"openapi":"3.1.0","info":{"title":"Microsoft Clarity (BYOK) API","version":"0.1.0","description":"Microsoft Clarity (BYOK) lets an AI assistant read your own Microsoft Clarity data through the Microsoft Clarity API with a key you supply (Clarity data export API token (project admin, Settings > Data Export)). Read-only: 6 tools (get_project_overview, get_insights_by_device, get_insights_by_country, get_insights_by_source, get_insights_by_page, get_insights_by_dimensions). The BYOK key travels...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-microsoft-clarity.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-microsoft-clarity/docs"},"termsOfService":"https://connectorbay.com/byok-microsoft-clarity/terms"},"servers":[{"url":"https://byok-microsoft-clarity.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-microsoft-clarity/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_project_overview":{"post":{"operationId":"get_project_overview","summary":"Get the project's dashboard metrics (traffic, scroll depth, engagement time, popular pages, dead and rage clicks, script","description":"Get the project's dashboard metrics (traffic, scroll depth, engagement time, popular pages, dead and rage clicks, script errors) for the last 1 to 3 days without any breakdown. The service allows 10 export calls per project per day, returns at most 1,000 rows and cannot paginate. Use for \"How did my Clarity project do over the last day\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"num_of_days":{"anyOf":[{"enum":[1,2,3],"type":"integer"},{"type":"null"}],"default":1,"description":"How many days back to export: 1, 2 or 3 (the last 24, 48 or 72 hours).","title":"Num Of Days"}},"title":"get_project_overviewArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_insights_by_device":{"post":{"operationId":"get_insights_by_device","summary":"Get dashboard metrics broken down by device type (and optionally a second dimension) for the last 1 to 3 days. The servi","description":"Get dashboard metrics broken down by device type (and optionally a second dimension) for the last 1 to 3 days. The service allows 10 export calls per project per day, returns at most 1,000 rows and cannot paginate. Use for \"How does Clarity traffic split by device\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"num_of_days":{"anyOf":[{"enum":[1,2,3],"type":"integer"},{"type":"null"}],"default":1,"description":"How many days back to export: 1, 2 or 3 (the last 24, 48 or 72 hours).","title":"Num Of Days"},"dimension1":{"anyOf":[{"enum":["Browser","Device","Country/Region","OS","Source","Medium","Campaign","Channel","URL"],"type":"string"},{"type":"null"}],"default":"Device","description":"First breakdown dimension.","title":"Dimension1"},"dimension2":{"anyOf":[{"enum":["Browser","Device","Country/Region","OS","Source","Medium","Campaign","Channel","URL"],"type":"string"},{"type":"null"}],"default":null,"description":"Optional second dimension, for example Browser or OS.","title":"Dimension2"}},"title":"get_insights_by_deviceArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_insights_by_country":{"post":{"operationId":"get_insights_by_country","summary":"Get dashboard metrics broken down by country or region (and optionally a second dimension) for the last 1 to 3 days. The","description":"Get dashboard metrics broken down by country or region (and optionally a second dimension) for the last 1 to 3 days. The service allows 10 export calls per project per day, returns at most 1,000 rows and cannot paginate. Use for \"Which countries send the most sessions in Clarity\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"num_of_days":{"anyOf":[{"enum":[1,2,3],"type":"integer"},{"type":"null"}],"default":1,"description":"How many days back to export: 1, 2 or 3 (the last 24, 48 or 72 hours).","title":"Num Of Days"},"dimension1":{"anyOf":[{"enum":["Browser","Device","Country/Region","OS","Source","Medium","Campaign","Channel","URL"],"type":"string"},{"type":"null"}],"default":"Country/Region","description":"First breakdown dimension.","title":"Dimension1"},"dimension2":{"anyOf":[{"enum":["Browser","Device","Country/Region","OS","Source","Medium","Campaign","Channel","URL"],"type":"string"},{"type":"null"}],"default":null,"description":"Optional second dimension, for example Device.","title":"Dimension2"}},"title":"get_insights_by_countryArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_insights_by_source":{"post":{"operationId":"get_insights_by_source","summary":"Get dashboard metrics broken down by traffic source and medium (or channel or campaign) for the last 1 to 3 days. The se","description":"Get dashboard metrics broken down by traffic source and medium (or channel or campaign) for the last 1 to 3 days. The service allows 10 export calls per project per day, returns at most 1,000 rows and cannot paginate. Use for \"Which traffic sources bring Clarity sessions\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"num_of_days":{"anyOf":[{"enum":[1,2,3],"type":"integer"},{"type":"null"}],"default":1,"description":"How many days back to export: 1, 2 or 3 (the last 24, 48 or 72 hours).","title":"Num Of Days"},"dimension1":{"anyOf":[{"enum":["Browser","Device","Country/Region","OS","Source","Medium","Campaign","Channel","URL"],"type":"string"},{"type":"null"}],"default":"Source","description":"First breakdown dimension.","title":"Dimension1"},"dimension2":{"anyOf":[{"enum":["Browser","Device","Country/Region","OS","Source","Medium","Campaign","Channel","URL"],"type":"string"},{"type":"null"}],"default":"Medium","description":"Optional second dimension.","title":"Dimension2"},"dimension3":{"anyOf":[{"enum":["Browser","Device","Country/Region","OS","Source","Medium","Campaign","Channel","URL"],"type":"string"},{"type":"null"}],"default":null,"description":"Optional third dimension, for example Campaign.","title":"Dimension3"}},"title":"get_insights_by_sourceArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_insights_by_page":{"post":{"operationId":"get_insights_by_page","summary":"Get dashboard metrics broken down by page URL (and optionally a second dimension) for the last 1 to 3 days. The service ","description":"Get dashboard metrics broken down by page URL (and optionally a second dimension) for the last 1 to 3 days. The service allows 10 export calls per project per day, returns at most 1,000 rows and cannot paginate. Use for \"Which pages have the most rage clicks in Clarity\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"num_of_days":{"anyOf":[{"enum":[1,2,3],"type":"integer"},{"type":"null"}],"default":1,"description":"How many days back to export: 1, 2 or 3 (the last 24, 48 or 72 hours).","title":"Num Of Days"},"dimension1":{"anyOf":[{"enum":["Browser","Device","Country/Region","OS","Source","Medium","Campaign","Channel","URL"],"type":"string"},{"type":"null"}],"default":"URL","description":"First breakdown dimension.","title":"Dimension1"},"dimension2":{"anyOf":[{"enum":["Browser","Device","Country/Region","OS","Source","Medium","Campaign","Channel","URL"],"type":"string"},{"type":"null"}],"default":null,"description":"Optional second dimension, for example Device.","title":"Dimension2"}},"title":"get_insights_by_pageArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_insights_by_dimensions":{"post":{"operationId":"get_insights_by_dimensions","summary":"Get dashboard metrics broken down by any one to three dimensions you choose: Browser, Device, Country/Region, OS, Source","description":"Get dashboard metrics broken down by any one to three dimensions you choose: Browser, Device, Country/Region, OS, Source, Medium, Campaign, Channel or URL. The service allows 10 export calls per project per day, returns at most 1,000 rows and cannot paginate. Use for \"Break Clarity sessions down by browser and OS for the last two days\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dimension1":{"description":"First breakdown dimension.","enum":["Browser","Device","Country/Region","OS","Source","Medium","Campaign","Channel","URL"],"title":"Dimension1","type":"string"},"num_of_days":{"anyOf":[{"enum":[1,2,3],"type":"integer"},{"type":"null"}],"default":1,"description":"How many days back to export: 1, 2 or 3 (the last 24, 48 or 72 hours).","title":"Num Of Days"},"dimension2":{"anyOf":[{"enum":["Browser","Device","Country/Region","OS","Source","Medium","Campaign","Channel","URL"],"type":"string"},{"type":"null"}],"default":null,"description":"Optional second dimension.","title":"Dimension2"},"dimension3":{"anyOf":[{"enum":["Browser","Device","Country/Region","OS","Source","Medium","Campaign","Channel","URL"],"type":"string"},{"type":"null"}],"default":null,"description":"Optional third dimension.","title":"Dimension3"}},"required":["dimension1"],"title":"get_insights_by_dimensionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}