Skip to content

docs(endpoints): steer production query traffic to endpoints - #22411

Open
kmt901 wants to merge 2 commits into
masterfrom
docs/steer-query-traffic-to-endpoints
Open

kmt901 wants to merge 2 commits into
masterfrom
docs/steer-query-traffic-to-endpoints

Conversation

@kmt901

@kmt901 kmt901 commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Changes

Developers who pull PostHog data into code, scheduled jobs, and customer-facing features read the API queries page, which lists embedded analytics as a use case and mentions Endpoints only under rate limits. That contradicts the Endpoints vs Query API page.

  • API queries: a callout at the top sends production, scheduled, and embedded use to Endpoints, agent questions to the MCP, and exports to batch exports. The embedded analytics use cases are removed.
  • Endpoints overview: new "When to use endpoints" section, and a walkthrough for moving a /query call to an endpoint.
  • Endpoints vs Query API: new rows for agents, scheduled jobs (materialization), and per-user lookups (variables).

Note

Overlaps draft #22399, which edits the same three pages for scheduled queries only. Close one before either merges.

Companion MCP PR: PostHog/posthog#136564

No visual changes beyond text. Not checked: the Vercel preview render.

Checklist

  • I've read the docs and/or content style guides.
  • Words are spelled using American English
  • Use relative URLs for internal links
  • I've checked the pages added or changed in the Vercel preview build
  • If I moved a page, I added a redirect in vercel.json

🤖 Generated with Claude Code

- API queries: lead with a callout sending production, scheduled, and
  embedded use to endpoints, the MCP, or batch exports, and drop the
  embedded analytics use cases
- Endpoints overview: add "When to use endpoints" and a walkthrough
  for moving a /query call to an endpoint
- Endpoints vs Query API: add rows for agents, scheduled jobs, and
  per-user lookups

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Vale prose linter → found 8 errors, 26 warnings, 2 suggestions in your markdown

Full report → Copy the linter results into an LLM to batch-fix issues.

Linter being weird? Update the rules!

contents/docs/api/queries.mdx — 0 errors, 8 warnings, 2 suggestions
Line Severity Message Rule
14:116 warning Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. PostHogBase.ProductNames
27:170 warning Capitalize 'Data Warehouse' for PostHog's product. Use 'data warehouse' for the general industry concept. PostHogBase.ProductNames
29:242 warning 'keyset' is a possible misspelling. PostHogBase.Spelling
51:57 warning 'keyset' is a possible misspelling. PostHogBase.Spelling
127:63 warning Capitalize 'Data Warehouse' for PostHog's product. Use 'data warehouse' for the general industry concept. PostHogBase.ProductNames
127:79 warning Capitalize 'Session Replay' for PostHog's product. Use 'session replay' for the general industry concept. PostHogBase.ProductNames
359:141 suggestion Address the reader directly. Use 'you' instead of 'the user'. PostHogDocs.DirectAddress
359:226 suggestion Address the reader directly. Use 'you' instead of 'the user'. PostHogDocs.DirectAddress
441:71 warning Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. PostHogBase.ProductNames
463:41 warning Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. PostHogBase.ProductNames
contents/docs/endpoints/endpoints-vs-query-api.mdx — 8 errors, 3 warnings, 0 suggestions
Line Severity Message Rule
14:1 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
15:1 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
16:1 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
22:1 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
22:39 warning Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. PostHogBase.ProductNames
23:1 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
24:1 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
25:1 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
26:1 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
26:37 warning Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. PostHogBase.ProductNames
32:14 warning 'explorative' is a possible misspelling. PostHogBase.Spelling
contents/docs/endpoints/index.mdx — 0 errors, 15 warnings, 0 suggestions
Line Severity Message Rule
13:67 warning Capitalize 'Logs' for PostHog's product. Use 'logs' for the general industry concept. PostHogBase.ProductNames
13:110 warning Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. PostHogBase.ProductNames
13:158 warning Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. PostHogBase.ProductNames
15:41 warning 'leaderboard' is a possible misspelling. PostHogBase.Spelling
15:90 warning Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. PostHogBase.ProductNames
41:111 warning Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. PostHogBase.ProductNames
58:23 warning Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. PostHogBase.ProductNames
58:147 warning Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. PostHogBase.ProductNames
66:63 warning Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. PostHogBase.ProductNames
66:133 warning Capitalize 'Logs' for PostHog's product. Use 'logs' for the general industry concept. PostHogBase.ProductNames
84:88 warning Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. PostHogBase.ProductNames
85:125 warning Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. PostHogBase.ProductNames
110:100 warning Capitalize 'Data Warehouse' for PostHog's product. Use 'data warehouse' for the general industry concept. PostHogBase.ProductNames
127:59 warning Capitalize 'Logs' for PostHog's product. Use 'logs' for the general industry concept. PostHogBase.ProductNames
129:131 warning Capitalize 'Logs' for PostHog's product. Use 'logs' for the general industry concept. PostHogBase.ProductNames

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Deploy preview

Status Details Updated (UTC)
🟢 Ready View preview Nov 16, 2026 05:26PM

Changed pages

Page Source
API queries contents/docs/api/queries.mdx
Endpoints contents/docs/endpoints/index.mdx
Endpoints vs Query API contents/docs/endpoints/endpoints-vs-query-api.mdx

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Bundle report

Total JS (gzip)

12.22 MiB (-0.0 KiB / -0.0%)

Eager graph (modules shipped in each entrypoint's initial chunks)

Entrypoint Eager size Budget Modules
✅ app 11.15 MiB (no change) report-only 1107
Largest modules in the app closure
Module Size
css ./node_modules/.pnpm/css-loader@5.2.7_webpack@5.101.3/node_modules/css-loader/dist/cjs.js??ruleSet[1].rules[8].oneOf[1].use[1]!./node_modules/.pnpm/postcss-loader@4.3.0_postcss@8.5.6_webpack@5.101.3/node_modules/postcss-loader/dist/cjs.js??ruleSet[1].rules[8].oneOf[1].use[2]!./src/styles/global.css 1023.1 KiB
./src/components/Stickers/Stickers.tsx 696.4 KiB
./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/puzzle.mjs 388.5 KiB
./node_modules/.pnpm/@posthog+icons@0.36.6_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/@posthog/icons/dist/posthog-icons.es.js 354.8 KiB
./node_modules/.pnpm/react-markdown@8.0.7_@types+react@16.14.66_react@18.3.1/node_modules/react-markdown/lib/react-markdown.js + 88 modules 351.4 KiB
./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/basketball-coach.mjs 337.4 KiB
./node_modules/.pnpm/framer-motion@14.0.0_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/framer-motion/dist/es/render/components/motion/proxy.mjs + 126 modules 287.2 KiB
./node_modules/.pnpm/cloudinary-core@2.14.0_lodash@4.17.21/node_modules/cloudinary-core/cloudinary-core.js 281.9 KiB
./src/components/SearchUI/index.tsx + 87 modules 273.1 KiB
./gatsby-browser.tsx + 60 modules 259.4 KiB
./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/construction-1.mjs 248.5 KiB
./src/components/Pricing/PricingSlider/Slider.tsx + 87 modules 240.2 KiB
./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/construction-2.mjs 228.2 KiB
./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/magnifying-glass.mjs 221.7 KiB
./src/hooks/useProduct.ts + 18 modules 166.8 KiB

Eager-graph budgets are report-only until a baseline is established. Sizes are gzip of public/**/*.js; eager size is webpack module source bytes for the modules actually shipped in the entrypoint's initial chunks (post-tree-shake).

@kmt901
kmt901 marked this pull request as ready for review November 16, 2026 16:49

@posthog posthog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PostHog Review · Standard · reviewed 7ee9091: 2 Should fix.

See this review and its findings in PostHog Review. Comment @posthog review --deep for a Deep review. A Deep review takes longer and looks deeper than a Standard review.

Comment thread contents/docs/endpoints/index.mdx Resolved
Comment thread contents/docs/endpoints/index.mdx Resolved
- define variables in the Variables tab before creating the endpoint
- get a key with the endpoint:read scope, since Query Read can't run
  endpoints
- limit and offset only apply to SQL endpoints
- capitalize Endpoints where the text means the product

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant