{"openapi":"3.1.0","info":{"title":"Plausible (BYOK) API","version":"0.1.0","description":"Plausible (BYOK) lets an AI assistant read your own Plausible data through the Plausible API with a key you supply (Stats API key (plausible.io only, not self-hosted)). Read-only: 9 tools (get_realtime_visitors, get_aggregate_stats, get_timeseries, get_breakdown, list_sites, list_teams, get_site, list_goals, list_custom_properties). 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-plausible.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-plausible/docs"},"termsOfService":"https://connectorbay.com/byok-plausible/terms"},"servers":[{"url":"https://byok-plausible.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-plausible/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_realtime_visitors":{"post":{"operationId":"get_realtime_visitors","summary":"Get the number of people who viewed a page of the site in the last 5 minutes. Use for \"How many visitors are on example.","description":"Get the number of people who viewed a page of the site in the last 5 minutes. Use for \"How many visitors are on example.com right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_id":{"description":"The site's domain as registered in Plausible, for example 'example.com'.","maxLength":200,"title":"Site Id","type":"string"}},"required":["site_id"],"title":"get_realtime_visitorsArguments","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_aggregate_stats":{"post":{"operationId":"get_aggregate_stats","summary":"Get totals (visitors, pageviews, bounce rate and so on) for a site over a period, optionally compared with the previous ","description":"Get totals (visitors, pageviews, bounce rate and so on) for a site over a period, optionally compared with the previous period. Use for \"How many visitors and pageviews did example.com have in the last 30 days\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_id":{"description":"The site's domain as registered in Plausible, for example 'example.com'.","maxLength":200,"title":"Site Id","type":"string"},"period":{"anyOf":[{"enum":["day","7d","30d","month","6mo","12mo","custom"],"type":"string"},{"type":"null"}],"default":"30d","description":"Time window: day, 7d, 30d, month, 6mo, 12mo, or custom (then also give date as 'YYYY-MM-DD,YYYY-MM-DD').","title":"Period"},"date":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Reference date 'YYYY-MM-DD' (default today in the site's time zone); for period=custom two dates 'YYYY-MM-DD,YYYY-MM-DD'.","title":"Date"},"metrics":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":"visitors","description":"Comma-separated metrics: visitors, visits, pageviews, views_per_visit, bounce_rate, visit_duration, events, conversion_rate (needs an event:goal filter) and time_on_page (needs an event:page filter). Default visitors.","title":"Metrics"},"compare":{"anyOf":[{"const":"previous_period","type":"string"},{"type":"null"}],"default":null,"description":"Set to previous_period to also get the change against the previous period.","title":"Compare"},"filters":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Optional filter expression, for example 'visit:country==US' or 'event:page==/blog/**'. Use == and != , | for OR, ; for AND, * as wildcard.","title":"Filters"}},"required":["site_id"],"title":"get_aggregate_statsArguments","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_timeseries":{"post":{"operationId":"get_timeseries","summary":"Get a site's stats per day or per month over a period, for charting a trend. Use for \"Show daily visitors for example.co","description":"Get a site's stats per day or per month over a period, for charting a trend. Use for \"Show daily visitors for example.com over the last 7 days\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_id":{"description":"The site's domain as registered in Plausible, for example 'example.com'.","maxLength":200,"title":"Site Id","type":"string"},"period":{"anyOf":[{"enum":["day","7d","30d","month","6mo","12mo","custom"],"type":"string"},{"type":"null"}],"default":"30d","description":"Time window: day, 7d, 30d, month, 6mo, 12mo, or custom (then also give date as 'YYYY-MM-DD,YYYY-MM-DD').","title":"Period"},"date":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Reference date 'YYYY-MM-DD' (default today in the site's time zone); for period=custom two dates 'YYYY-MM-DD,YYYY-MM-DD'.","title":"Date"},"metrics":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":"visitors","description":"Comma-separated metrics: visitors, visits, pageviews, views_per_visit, bounce_rate, visit_duration, events, conversion_rate. Default visitors.","title":"Metrics"},"interval":{"anyOf":[{"enum":["day","month"],"type":"string"},{"type":"null"}],"default":null,"description":"day or month (month only for periods longer than one calendar month). Default depends on the period.","title":"Interval"},"filters":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Optional filter expression, for example 'visit:country==US' or 'event:page==/blog/**'. Use == and != , | for OR, ; for AND, * as wildcard.","title":"Filters"}},"required":["site_id"],"title":"get_timeseriesArguments","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_breakdown":{"post":{"operationId":"get_breakdown","summary":"Break a site's stats down by one property such as page, source, country, device or UTM tag, ranked by the first metric. ","description":"Break a site's stats down by one property such as page, source, country, device or UTM tag, ranked by the first metric. Use for \"What are the top traffic sources for example.com this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_id":{"description":"The site's domain as registered in Plausible, for example 'example.com'.","maxLength":200,"title":"Site Id","type":"string"},"property":{"description":"What to group by: event:page, event:goal, visit:entry_page, visit:exit_page, visit:source, visit:referrer, visit:utm_medium, visit:utm_source, visit:utm_campaign, visit:device, visit:browser, visit:os, visit:country, visit:region, visit:city, or event:props:<name>.","maxLength":100,"title":"Property","type":"string"},"period":{"anyOf":[{"enum":["day","7d","30d","month","6mo","12mo","custom"],"type":"string"},{"type":"null"}],"default":"30d","description":"Time window: day, 7d, 30d, month, 6mo, 12mo, or custom (then also give date as 'YYYY-MM-DD,YYYY-MM-DD').","title":"Period"},"date":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Reference date 'YYYY-MM-DD' (default today in the site's time zone); for period=custom two dates 'YYYY-MM-DD,YYYY-MM-DD'.","title":"Date"},"metrics":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":"visitors","description":"Comma-separated metrics: visitors, visits, pageviews, views_per_visit, bounce_rate, visit_duration, events, conversion_rate (needs an event:goal filter) and time_on_page (needs an event:page filter). Default visitors.","title":"Metrics"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many rows to return (1 to 1000, default 100).","title":"Limit"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1, to go beyond the limit.","title":"Page"},"filters":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Optional filter expression, for example 'visit:country==US' or 'event:page==/blog/**'. Use == and != , | for OR, ; for AND, * as wildcard.","title":"Filters"}},"required":["site_id","property"],"title":"get_breakdownArguments","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/list_sites":{"post":{"operationId":"list_sites","summary":"List the sites your Plausible key can read, with time zone, using cursor paging. Use for \"Which sites do I have in Plaus","description":"List the sites your Plausible key can read, with time zone, using cursor paging. Use for \"Which sites do I have in Plausible\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"team_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only sites of this team id (see list_teams).","title":"Team Id"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many results to return (1 to 100).","title":"Limit"},"after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's meta.after to get the next page.","title":"After"},"before":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's meta.before to get the previous page.","title":"Before"}},"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/list_teams":{"post":{"operationId":"list_teams","summary":"List the Plausible teams the key can see, with whether the Stats API is available to each. Use for \"Which Plausible team","description":"List the Plausible teams the key can see, with whether the Stats API is available to each. Use for \"Which Plausible teams can my key use\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many results to return (1 to 100).","title":"Limit"},"after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's meta.after to get the next page.","title":"After"},"before":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's meta.before to get the previous page.","title":"Before"}},"title":"list_teamsArguments","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_site":{"post":{"operationId":"get_site","summary":"Get one site's time zone, custom properties and tracker script settings. Use for \"What is the time zone and tracker setu","description":"Get one site's time zone, custom properties and tracker script settings. Use for \"What is the time zone and tracker setup of example.com in Plausible\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_id":{"description":"The site's domain, for example 'example.com'.","maxLength":200,"title":"Site Id","type":"string"}},"required":["site_id"],"title":"get_siteArguments","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/list_goals":{"post":{"operationId":"list_goals","summary":"List a site's conversion goals (custom events and page goals) with their type, name and path. Use for \"What goals are co","description":"List a site's conversion goals (custom events and page goals) with their type, name and path. Use for \"What goals are configured for example.com in Plausible\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_id":{"description":"The site's domain as registered in Plausible, for example 'example.com'.","maxLength":200,"title":"Site Id","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many results to return (1 to 100).","title":"Limit"},"after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's meta.after to get the next page.","title":"After"},"before":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's meta.before to get the previous page.","title":"Before"}},"required":["site_id"],"title":"list_goalsArguments","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/list_custom_properties":{"post":{"operationId":"list_custom_properties","summary":"List the custom event property names defined for a site. Use for \"Which custom properties does example.com track in Plau","description":"List the custom event property names defined for a site. Use for \"Which custom properties does example.com track in Plausible\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_id":{"description":"The site's domain as registered in Plausible, for example 'example.com'.","maxLength":200,"title":"Site Id","type":"string"}},"required":["site_id"],"title":"list_custom_propertiesArguments","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}}}}