> ## Documentation Index > Fetch the complete documentation index at: https://docs.upstackdata.com/llms.txt > Use this file to discover all available pages before exploring further. # Search products > Search products by title / SKU / variant. Cursor-paginated. Pass `ids` instead to fetch specific products by id. That looks them up directly rather than searching, so `q`, `pageSize` and `cursor` are ignored and `pagination.hasMore` is always `false`. **Required scope:** `costs:read`. ## OpenAPI ````yaml /api-reference/openapi.yaml get /accounts/api/products/search openapi: 3.1.0 info: title: Upstack Data API version: '1.0' description: > Programmatic access to your Upstack Data pixel — analytics queries, the measures/dimensions catalog, and dashboard view management. All requests authenticate with two headers: - `x-api-key`: your Upstack API key (mint one at **Settings → API Keys** in the dashboard). - `x-pixel-id`: the pixel id the request targets. One key is scoped to one pixel. servers: - url: https://api.upstackdata.com description: Production security: - apiKey: [] pixelId: [] tags: - name: Analytics description: Query events, attribution, and cohort analyses. - name: Catalog description: List the measures available to your pixel. - name: Dashboards description: >- Manage dashboard views — create, update, copy, delete, and the high-level preset builder. - name: Account description: >- Read and update the account that owns this API key — display name, active owners and admins, and subscription summary. - name: Costs description: >- Read and update every cost surface — global product overrides, shipping method, per-variant handling fees and COGS history, and per-type cost lines (order / gateway / shipping profile / variable / fixed). Mutations trigger the same per-order COGS recalculation as web-UI changes. - name: Products description: Browse products + variants in the configured catalog. - name: Events description: >- Upstack Conversion API (CAPI) — send server-side tracking events from your backend. paths: /accounts/api/products/search: get: tags: - Products summary: Search products description: | Search products by title / SKU / variant. Cursor-paginated. Pass `ids` instead to fetch specific products by id. That looks them up directly rather than searching, so `q`, `pageSize` and `cursor` are ignored and `pagination.hasMore` is always `false`. **Required scope:** `costs:read`. operationId: searchProducts parameters: - name: q in: query schema: type: string description: Search term (matched against title / SKU / variant). - name: pageSize in: query schema: type: integer minimum: 1 maximum: 100 default: 20 - name: cursor in: query schema: type: string description: Pagination cursor from a previous response's `pagination.cursor`. - name: ids in: query schema: type: string description: | Comma-separated product ids. Fetches those products directly instead of searching. Duplicates are ignored; at most 100 ids per request. - name: includeVariants in: query schema: type: boolean description: | Whether each product carries its `variants`. Defaults to `true` when searching and `false` when fetching by `ids`. responses: '200': description: A page of products with their variants. content: application/json: schema: $ref: '#/components/schemas/ProductSearchResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' components: schemas: ProductSearchResponse: type: object required: - products - pagination properties: products: type: array items: $ref: '#/components/schemas/ProductSummary' pagination: type: object required: - hasMore properties: hasMore: type: boolean description: Whether another page is available. cursor: type: string description: >- Cursor to pass as `?cursor=` to fetch the next page. Absent when there are no more pages. ProductSummary: type: object description: A product with its variants for search results. required: - productId - productTitle - imageUrls - hasOnlyDefaultVariant - variants properties: productId: type: string productTitle: type: string handle: type: string vendor: type: string productType: type: string imageUrls: type: array items: type: string hasOnlyDefaultVariant: type: boolean description: True when Shopify created a single unnamed "Default Title" variant. variants: type: array items: $ref: '#/components/schemas/ProductSearchVariant' Error: type: object required: - message properties: message: type: string description: Human-readable error message. errors: type: array description: Per-field validation errors (present on 400 responses). items: type: object properties: message: type: string key: type: string path: type: array items: type: string ProductSearchVariant: type: object description: > A variant as returned by product search — costs are already resolved, so no cost history is included. required: - variantId - variantTitle - sku properties: variantId: type: string variantTitle: type: string sku: type: string currency: type: string currentPrice: type: number shopifyCost: type: number description: Cost synced from Shopify inventory (read-only). effectiveCost: type: number description: >- The cost actually used — the manual override when set, otherwise `shopifyCost`. costSource: type: string enum: - manual - shopify description: Where `effectiveCost` came from. Absent when neither cost is set. handlingFee: type: number quantity: type: integer description: Shopify inventory quantity. responses: BadRequest: description: Validation error. Includes an `errors` array with per-field detail. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: > The `x-api-key` or `x-pixel-id` header is missing. The request is rejected before it reaches the API, and the body is `{"message": "Unauthorized"}`. A key that is present but not accepted returns `403`, not `401`. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: > The key was rejected, or it is valid but not allowed to do this. Either: - the key is unknown, revoked, or expired, or the pixel is inactive — the body is `{"Message": "User is not authorized to access this resource with an explicit deny in an identity-based policy"}` (note the capital `M`); - the key doesn't carry the scope this endpoint needs, or the body `pixelId` doesn't match the `x-pixel-id` header — the body is `{"message": "…"}` as described below. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: Your Upstack API key. Starts with `upstack_`. pixelId: type: apiKey in: header name: x-pixel-id description: The pixel id the request targets. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.