Frontend Data Fetching (TanStack Query + apiOptions)
Use apiOptions with useQuery from TanStack Query. Do not use useApiQuery, getApiQueryData, or setApiQueryData — they are deprecated.
import {skipToken, useQuery} from '@tanstack/react-query';
import {apiOptions} from 'sentry/utils/api/apiOptions';
// Basic usage
const query = useQuery(
apiOptions.as<ResponseType>()('/organizations/$organizationIdOrSlug/endpoint/', {
path: {organizationIdOrSlug: organization.slug},
staleTime: 30_000,
})
);
// Conditional fetching — pass skipToken as path to disable the query
const query = useQuery(
apiOptions.as<ResponseType>()('/organizations/$organizationIdOrSlug/items/$itemId/', {
path: itemId ? {organizationIdOrSlug: organization.slug, itemId} : skipToken,
staleTime: 30_000,
})
);
Key rules:
staleTime is required — you must choose a value (0, a number in ms, Infinity, or 'static').
- Build abstractions over
apiOptions, not over useQuery. Return the options object so consumers can pass it to useQuery, useQueries, prefetchQuery, etc.
- Cache stores
{json, headers}, not just the body. apiOptions uses select to extract .json by default, but getQueryData, setQueryData, retry functions, and predicate callbacks all receive the raw ApiResponse<T> shape.
- never use
api.requestPromise for a Query - it returns the wrong structure. If you must make a manual queryFn, use apiFetch.
TanStack Query Type Inference — NEVER Pass Call-Site Generics
CRITICAL: Never pass type parameters to useQuery, useMutation, mutationOptions, queryOptions, or any TanStack Query function at the call site. Let TypeScript infer types from your queryFn/mutationFn and callbacks. Passing call-site generics defeats inference, hides bugs, and creates maintenance burden.
// ❌ NEVER pass generics to useQuery, useMutation, mutationOptions, etc.
useMutation<ResponseType, RequestError, Variables, Context>({...})
mutationOptions<ResponseType, RequestError, Variables, Context>({...})
useQuery<ResponseType, RequestError>({...})
// ✅ Let types be inferred — annotate the mutationFn/queryFn instead
useMutation({
mutationFn: (variables: MyVariables) =>
fetchMutation<MyResponse>({...}),
})
Specific rules:
- Type the
mutationFn parameters, not the hook/function generics. The variables type flows from the mutationFn signature.
- Use
fetchMutation<T> to type the return value — the generic on fetchMutation is correct because it types the API response.
- Never type the error generic as
RequestError — that's a type assertion in disguise. The error is Error by default. Use runtime narrowing (if (error instanceof RequestError)) when you need RequestError-specific properties.
- Never explicitly type the context — it is inferred from what
onMutate returns. Creating a separate type FooContext = {...} and passing it as a generic is unnecessary.
- Same rule applies to queries —
useQuery, queryOptions, useInfiniteQuery, etc. Types flow from queryFn and select.
// ❌ Explicit context type + error assertion
type MyContext = {previousData: Item[]};
mutationOptions<Item, RequestError, UpdateItemVars, MyContext>({
mutationFn: variables => fetchMutation({...}),
onMutate: async () => {
const previousData = queryClient.getQueryData(itemQueryOptions);
return {previousData};
},
onError: (_error, _variables, context) => {
queryClient.setQueryData(key, context?.previousData);
},
})
// ✅ Everything is inferred
mutationOptions({
mutationFn: (variables: UpdateItemVars) =>
fetchMutation<Item>({...}),
onMutate: async () => {
const previousData = queryClient.getQueryData(itemQueryOptions);
return {previousData};
},
onError: (_error, _variables, context) => {
// context type is inferred from onMutate return
queryClient.setQueryData(key, context?.previousData);
},
})
Accessing response headers (pagination, hit counts)
By default, apiOptions selects only the JSON body from the response. If you need response headers (e.g., Link for pagination or X-Hits / X-Max-Hits for total counts), override select with selectJsonWithHeaders:
import {useQuery} from '@tanstack/react-query';
import {apiOptions, selectJsonWithHeaders} from 'sentry/utils/api/apiOptions';
const {data} = useQuery({
...apiOptions.as<Item[]>()('/organizations/$organizationIdOrSlug/items/', {
path: {organizationIdOrSlug: organization.slug},
query: {cursor, per_page: 25},
staleTime: 0,
}),
select: selectJsonWithHeaders,
});
// data is ApiResponse<Item[]> — an object with `json` and `headers`
const items = data?.json ?? [];
const pageLinks = data?.headers.Link; // string | undefined
const totalHits = data?.headers['X-Hits']; // number | undefined
const maxHits = data?.headers['X-Max-Hits']; // number | undefined
Note that X-Hits and X-Max-Hits are already parsed to number | undefined — no parseInt needed.
1---2name: frontend-data-fetching3description: Fetch data in Sentry's frontend with TanStack Query and apiOptions. Use when adding or editing React code in static/ that calls the API — useQuery/useMutation/useInfiniteQuery, apiOptions, queryOptions/mutationOptions, fetchMutation, reading response headers/pagination, or conditional fetching. Trigger on "fetch data", "add an API call", "useQuery", "useMutation", "apiOptions", "queryFn", "pagination headers", "X-Hits", or "why is my query type wrong".4metadata:5 source: https://skillmd.com/skills/getsentry/frontend-data-fetching6---78# Frontend Data Fetching (TanStack Query + apiOptions)910Use `apiOptions` with `useQuery` from TanStack Query. **Do not use `useApiQuery`, `getApiQueryData`, or `setApiQueryData`** — they are deprecated.1112```typescript13import {skipToken, useQuery} from '@tanstack/react-query';14import {apiOptions} from 'sentry/utils/api/apiOptions';1516// Basic usage17const query = useQuery(18 apiOptions.as<ResponseType>()('/organizations/$organizationIdOrSlug/endpoint/', {19 path: {organizationIdOrSlug: organization.slug},20 staleTime: 30_000,21 })22);2324// Conditional fetching — pass skipToken as path to disable the query25const query = useQuery(26 apiOptions.as<ResponseType>()('/organizations/$organizationIdOrSlug/items/$itemId/', {27 path: itemId ? {organizationIdOrSlug: organization.slug, itemId} : skipToken,28 staleTime: 30_000,29 })30);31```3233Key rules:3435- **`staleTime` is required** — you must choose a value (`0`, a number in ms, `Infinity`, or `'static'`).36- **Build abstractions over `apiOptions`**, not over `useQuery`. Return the options object so consumers can pass it to `useQuery`, `useQueries`, `prefetchQuery`, etc.37- **Cache stores `{json, headers}`**, not just the body. `apiOptions` uses `select` to extract `.json` by default, but `getQueryData`, `setQueryData`, `retry` functions, and `predicate` callbacks all receive the raw `ApiResponse<T>` shape.38- **never** use `api.requestPromise` for a Query - it returns the wrong structure. If you must make a manual `queryFn`, use `apiFetch`.3940## TanStack Query Type Inference — NEVER Pass Call-Site Generics4142**CRITICAL**: Never pass type parameters to `useQuery`, `useMutation`, `mutationOptions`, `queryOptions`, or any TanStack Query function at the call site. Let TypeScript infer types from your `queryFn`/`mutationFn` and callbacks. Passing call-site generics defeats inference, hides bugs, and creates maintenance burden.4344```typescript45// ❌ NEVER pass generics to useQuery, useMutation, mutationOptions, etc.46useMutation<ResponseType, RequestError, Variables, Context>({...})47mutationOptions<ResponseType, RequestError, Variables, Context>({...})48useQuery<ResponseType, RequestError>({...})4950// ✅ Let types be inferred — annotate the mutationFn/queryFn instead51useMutation({52 mutationFn: (variables: MyVariables) =>53 fetchMutation<MyResponse>({...}),54})55```5657Specific rules:58591. **Type the `mutationFn` parameters**, not the hook/function generics. The variables type flows from the `mutationFn` signature.602. **Use `fetchMutation<T>`** to type the return value — the generic on `fetchMutation` is correct because it types the API response.613. **Never type the error generic as `RequestError`** — that's a type assertion in disguise. The error is `Error` by default. Use runtime narrowing (`if (error instanceof RequestError)`) when you need `RequestError`-specific properties.624. **Never explicitly type the context** — it is inferred from what `onMutate` returns. Creating a separate `type FooContext = {...}` and passing it as a generic is unnecessary.635. **Same rule applies to queries** — `useQuery`, `queryOptions`, `useInfiniteQuery`, etc. Types flow from `queryFn` and `select`.6465```typescript66// ❌ Explicit context type + error assertion67type MyContext = {previousData: Item[]};6869mutationOptions<Item, RequestError, UpdateItemVars, MyContext>({70 mutationFn: variables => fetchMutation({...}),71 onMutate: async () => {72 const previousData = queryClient.getQueryData(itemQueryOptions);73 return {previousData};74 },75 onError: (_error, _variables, context) => {76 queryClient.setQueryData(key, context?.previousData);77 },78})7980// ✅ Everything is inferred81mutationOptions({82 mutationFn: (variables: UpdateItemVars) =>83 fetchMutation<Item>({...}),84 onMutate: async () => {85 const previousData = queryClient.getQueryData(itemQueryOptions);86 return {previousData};87 },88 onError: (_error, _variables, context) => {89 // context type is inferred from onMutate return90 queryClient.setQueryData(key, context?.previousData);91 },92})93```9495## Accessing response headers (pagination, hit counts)9697By default, `apiOptions` selects only the JSON body from the response. If you need response headers (e.g., `Link` for pagination or `X-Hits` / `X-Max-Hits` for total counts), override `select` with `selectJsonWithHeaders`:9899```typescript100import {useQuery} from '@tanstack/react-query';101import {apiOptions, selectJsonWithHeaders} from 'sentry/utils/api/apiOptions';102103const {data} = useQuery({104 ...apiOptions.as<Item[]>()('/organizations/$organizationIdOrSlug/items/', {105 path: {organizationIdOrSlug: organization.slug},106 query: {cursor, per_page: 25},107 staleTime: 0,108 }),109 select: selectJsonWithHeaders,110});111112// data is ApiResponse<Item[]> — an object with `json` and `headers`113const items = data?.json ?? [];114const pageLinks = data?.headers.Link; // string | undefined115const totalHits = data?.headers['X-Hits']; // number | undefined116const maxHits = data?.headers['X-Max-Hits']; // number | undefined117```118119Note that `X-Hits` and `X-Max-Hits` are already parsed to `number | undefined` — no `parseInt` needed.