{"openapi":"3.1.0","info":{"title":"GoSquared (BYOK) API","version":"0.1.0","description":"GoSquared (BYOK) lets an AI assistant read your own GoSquared data through the GoSquared API with a key you supply (GoSquared API key). Read-only: 12 tools (list_sites, now_overview, now_concurrents, now_pages, now_sources, now_countries, now_browsers, now_engagement, trends_aggregate, trends_pages, trends_sources, trends_countries). The BYOK key travels with each request, is used for that one...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-gosquared.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-gosquared/docs"},"termsOfService":"https://connectorbay.com/byok-gosquared/terms"},"servers":[{"url":"https://byok-gosquared.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-gosquared/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/list_sites":{"post":{"operationId":"list_sites","summary":"List the sites (projects) the key's account owns or has shared access to, including their site tokens. Use for \"Which Go","description":"List the sites (projects) the key's account owns or has shared access to, including their site tokens. Use for \"Which GoSquared sites can I see\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"presenter":{"anyOf":[{"enum":["grouped","flat"],"type":"string"},{"type":"null"}],"default":"grouped","description":"Answer layout: grouped (by ownership) or flat (one list).","title":"Presenter"}},"title":"list_sitesArguments","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/now_overview":{"post":{"operationId":"now_overview","summary":"Real-time summary for a site: people online, active pages and historical visitor minimum, maximum and average for the pe","description":"Real-time summary for a site: people online, active pages and historical visitor minimum, maximum and average for the period. Use for \"How many people are on my website right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_token":{"description":"Site (project) token of the GoSquared project, for example 'GSN-106863-S' (list_sites returns it).","maxLength":40,"title":"Site Token","type":"string"},"from_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the comparison period as a date-time.","title":"From Time"},"to_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"End of the comparison period as a date-time.","title":"To Time"}},"required":["site_token"],"title":"now_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/now_concurrents":{"post":{"operationId":"now_concurrents","summary":"Summary of all visitors currently online on a site. Use for \"How many concurrent visitors does my GoSquared site have\".","description":"Summary of all visitors currently online on a site. Use for \"How many concurrent visitors does my GoSquared site have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_token":{"description":"Site (project) token of the GoSquared project, for example 'GSN-106863-S' (list_sites returns it).","maxLength":40,"title":"Site Token","type":"string"}},"required":["site_token"],"title":"now_concurrentsArguments","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/now_pages":{"post":{"operationId":"now_pages","summary":"Pages with visitors online right now, most visitors first; pass href to look at one page. Use for \"Which pages are visit","description":"Pages with visitors online right now, most visitors first; pass href to look at one page. Use for \"Which pages are visitors viewing right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_token":{"description":"Site (project) token of the GoSquared project, for example 'GSN-106863-S' (list_sites returns it).","maxLength":40,"title":"Site Token","type":"string"},"href":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Full URL of one page to look up (leave out to list all active pages).","title":"Href"},"limit":{"anyOf":[{"maxLength":12,"type":"string"},{"type":"null"}],"default":"0,10","description":"Maximum pages to return, as 'count' or 'offset,count' (for example '10' or '5,10'); default 0,10.","title":"Limit"}},"required":["site_token"],"title":"now_pagesArguments","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/now_sources":{"post":{"operationId":"now_sources","summary":"Where currently online visitors came from, grouped into direct, organic, site, social and internal sources. Use for \"Whe","description":"Where currently online visitors came from, grouped into direct, organic, site, social and internal sources. Use for \"Where are my live visitors coming from\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_token":{"description":"Site (project) token of the GoSquared project, for example 'GSN-106863-S' (list_sites returns it).","maxLength":40,"title":"Site Token","type":"string"},"limit":{"anyOf":[{"maxLength":12,"type":"string"},{"type":"null"}],"default":"0,10","description":"Maximum sources per group to return, as 'count' or 'offset,count' (for example '10' or '5,10'); default 0,10.","title":"Limit"},"drill_limit":{"anyOf":[{"maxLength":12,"type":"string"},{"type":"null"}],"default":"0,5","description":"Maximum results inside each source group, as 'count' or 'offset,count'; default 0,5.","title":"Drill Limit"},"sections":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":"direct,site,social,organic,internal","description":"Comma-separated source types to return: direct, site, social, organic, internal.","title":"Sections"},"minimal":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True for a compact answer.","title":"Minimal"}},"required":["site_token"],"title":"now_sourcesArguments","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/now_countries":{"post":{"operationId":"now_countries","summary":"Countries of the visitors currently online, most visitors first. Use for \"Which countries are my live visitors in\".","description":"Countries of the visitors currently online, most visitors first. Use for \"Which countries are my live visitors in\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_token":{"description":"Site (project) token of the GoSquared project, for example 'GSN-106863-S' (list_sites returns it).","maxLength":40,"title":"Site Token","type":"string"},"limit":{"anyOf":[{"maxLength":12,"type":"string"},{"type":"null"}],"default":"0,5","description":"Maximum countries to return, as 'count' or 'offset,count' (for example '10' or '5,10'); default 0,5.","title":"Limit"},"presenter":{"anyOf":[{"enum":["truncatedList","list","truncatedObject","object"],"type":"string"},{"type":"null"}],"default":"truncatedList","description":"Answer layout: truncatedList (list plus an 'other' total), list, truncatedObject or object (item:count pairs).","title":"Presenter"}},"required":["site_token"],"title":"now_countriesArguments","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/now_browsers":{"post":{"operationId":"now_browsers","summary":"Browsers used by the visitors currently online, most visitors first. Use for \"Which browsers are my live visitors using\"","description":"Browsers used by the visitors currently online, most visitors first. Use for \"Which browsers are my live visitors using\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_token":{"description":"Site (project) token of the GoSquared project, for example 'GSN-106863-S' (list_sites returns it).","maxLength":40,"title":"Site Token","type":"string"},"limit":{"anyOf":[{"maxLength":12,"type":"string"},{"type":"null"}],"default":"0,5","description":"Maximum browsers to return, as 'count' or 'offset,count' (for example '10' or '5,10'); default 0,5.","title":"Limit"},"presenter":{"anyOf":[{"enum":["truncatedList","list","truncatedObject","object"],"type":"string"},{"type":"null"}],"default":"truncatedList","description":"Answer layout: truncatedList (list plus an 'other' total), list, truncatedObject or object (item:count pairs).","title":"Presenter"}},"required":["site_token"],"title":"now_browsersArguments","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/now_engagement":{"post":{"operationId":"now_engagement","summary":"Real-time engagement of online visitors: time-on-site and visit-depth breakdowns with averages. Use for \"How long have m","description":"Real-time engagement of online visitors: time-on-site and visit-depth breakdowns with averages. Use for \"How long have my live visitors been on the site\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_token":{"description":"Site (project) token of the GoSquared project, for example 'GSN-106863-S' (list_sites returns it).","maxLength":40,"title":"Site Token","type":"string"}},"required":["site_token"],"title":"now_engagementArguments","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/trends_aggregate":{"post":{"operationId":"trends_aggregate","summary":"Historical summary metrics for a site over a period, split by hour, day or month. Use for \"How many visitors did my site","description":"Historical summary metrics for a site over a period, split by hour, day or month. Use for \"How many visitors did my site have each day last week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_token":{"description":"Site (project) token of the GoSquared project, for example 'GSN-106863-S' (list_sites returns it).","maxLength":40,"title":"Site Token","type":"string"},"from_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the period as a date-time, for example 2026-10-01 (defaults to the service's own range when left out).","title":"From Time"},"to_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"End of the period as a date-time, for example 2026-10-07.","title":"To Time"},"limit":{"anyOf":[{"maxLength":12,"type":"string"},{"type":"null"}],"default":"0,20","description":"Maximum data points to return, as 'count' or 'offset,count' (for example '10' or '5,10'); default 0,20.","title":"Limit"},"interval":{"anyOf":[{"enum":["hour","day","month"],"type":"string"},{"type":"null"}],"default":"day","description":"Group data points by hour, day or month.","title":"Interval"}},"required":["site_token"],"title":"trends_aggregateArguments","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/trends_pages":{"post":{"operationId":"trends_pages","summary":"Historical page metrics for a site over a period, most viewed first. Use for \"Which pages got the most views last month\"","description":"Historical page metrics for a site over a period, most viewed first. Use for \"Which pages got the most views last month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_token":{"description":"Site (project) token of the GoSquared project, for example 'GSN-106863-S' (list_sites returns it).","maxLength":40,"title":"Site Token","type":"string"},"from_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the period as a date-time, for example 2026-10-01 (defaults to the service's own range when left out).","title":"From Time"},"to_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"End of the period as a date-time, for example 2026-10-07.","title":"To Time"},"limit":{"anyOf":[{"maxLength":12,"type":"string"},{"type":"null"}],"default":"0,20","description":"Maximum pages to return, as 'count' or 'offset,count' (for example '10' or '5,10'); default 0,20.","title":"Limit"}},"required":["site_token"],"title":"trends_pagesArguments","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/trends_sources":{"post":{"operationId":"trends_sources","summary":"Historical referral sources for a site over a period, optionally for one source type and grouped by engine or domain. Us","description":"Historical referral sources for a site over a period, optionally for one source type and grouped by engine or domain. Use for \"Which referral sites sent the most traffic last month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_token":{"description":"Site (project) token of the GoSquared project, for example 'GSN-106863-S' (list_sites returns it).","maxLength":40,"title":"Site Token","type":"string"},"from_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the period as a date-time, for example 2026-10-01 (defaults to the service's own range when left out).","title":"From Time"},"to_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"End of the period as a date-time, for example 2026-10-07.","title":"To Time"},"limit":{"anyOf":[{"maxLength":12,"type":"string"},{"type":"null"}],"default":"0,20","description":"Maximum sources to return, as 'count' or 'offset,count' (for example '10' or '5,10'); default 0,20.","title":"Limit"},"source_type":{"anyOf":[{"enum":["site","social","organic","internal"],"type":"string"},{"type":"null"}],"default":null,"description":"Only this source type: site, social, organic or internal.","title":"Source Type"},"group":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to group results by search engine or site domain (needs source_type).","title":"Group"}},"required":["site_token"],"title":"trends_sourcesArguments","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/trends_countries":{"post":{"operationId":"trends_countries","summary":"Historical visitor metrics by country for a site over a period. Use for \"Which countries had the most visitors last mont","description":"Historical visitor metrics by country for a site over a period. Use for \"Which countries had the most visitors last month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_token":{"description":"Site (project) token of the GoSquared project, for example 'GSN-106863-S' (list_sites returns it).","maxLength":40,"title":"Site Token","type":"string"},"from_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the period as a date-time, for example 2026-10-01 (defaults to the service's own range when left out).","title":"From Time"},"to_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"End of the period as a date-time, for example 2026-10-07.","title":"To Time"},"limit":{"anyOf":[{"maxLength":12,"type":"string"},{"type":"null"}],"default":"0,20","description":"Maximum countries to return, as 'count' or 'offset,count' (for example '10' or '5,10'); default 0,20.","title":"Limit"}},"required":["site_token"],"title":"trends_countriesArguments","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}}}}