> ## Documentation Index > Fetch the complete documentation index at: https://docs.upriver.ai/llms.txt > Use this file to discover all available pages before exploring further. # Products List > Returns a list of products associated with a brand. Requires **brand_url** on every request, including pagination requests that send **cursor**. When **cursor** is provided, **brand_url** must match the brand encoded in that cursor. Response format: - **json**: Returns structured data with product list (default) - **text**: Returns natural language report Returns verified products and services; pricing plans, features, gift cards, documentation and signup actions are excluded. Use limit=1–20 and optionally filter by tier: primary or secondary. Products are discovered in bounded batches, with primary offerings preferred within each batch; this is not a global ranking or an exhaustive catalog. Continue with next_cursor and the same tier filter. A page may be empty while has_more is true. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/brand/products openapi: 3.1.0 info: title: Upriver API description: >- A social insights API for ad generation platforms. It provides structured signals, like psychographics, behavioral insights, trends, and audience language, to help AI models generate relevant, higher-converting ads. version: 1.0.0 servers: - url: https://api.upriver.ai description: Production API server security: [] tags: - name: Brands - name: Products - name: Creators - name: Audience - name: Sponsorships - name: Trends - name: Breakout Topics - name: Taxonomy paths: /v1/brand/products: post: tags: - Products summary: Products List description: >- Returns a list of products associated with a brand. Requires **brand_url** on every request, including pagination requests that send **cursor**. When **cursor** is provided, **brand_url** must match the brand encoded in that cursor. Response format: - **json**: Returns structured data with product list (default) - **text**: Returns natural language report Returns verified products and services; pricing plans, features, gift cards, documentation and signup actions are excluded. Use limit=1–20 and optionally filter by tier: primary or secondary. Products are discovered in bounded batches, with primary offerings preferred within each batch; this is not a global ranking or an exhaustive catalog. Continue with next_cursor and the same tier filter. A page may be empty while has_more is true. operationId: brand_product requestBody: content: application/json: schema: $ref: '#/components/schemas/BrandProductInput' examples: all: summary: All products description: >- Multiple products can be primary. Unfiltered results also include products whose relationship is unset; non-products are excluded. Change brand_url to the brand you want to research. value: brand_url: https://glossier.com limit: 5 include: - description - image_url all_next_page: summary: All products — next page description: >- Multiple products can be primary. Unfiltered results also include products whose relationship is unset; non-products are excluded. Replace cursor with next_cursor from the preceding response for this same brand and tier filter. Continue while has_more is true, even if products is empty. value: brand_url: https://glossier.com limit: 5 include: - description - image_url cursor: REPLACE_WITH_NEXT_CURSOR primary: summary: Primary products description: >- Multiple products can be primary. Unfiltered results also include products whose relationship is unset; non-products are excluded. Change brand_url to the brand you want to research. value: brand_url: https://glossier.com limit: 5 include: - description - image_url tier: primary primary_next_page: summary: Primary products — next page description: >- Multiple products can be primary. Unfiltered results also include products whose relationship is unset; non-products are excluded. Replace cursor with next_cursor from the preceding response for this same brand and tier filter. Continue while has_more is true, even if products is empty. value: brand_url: https://glossier.com limit: 5 include: - description - image_url tier: primary cursor: REPLACE_WITH_NEXT_CURSOR secondary: summary: Secondary products description: >- Multiple products can be primary. Unfiltered results also include products whose relationship is unset; non-products are excluded. Change brand_url to the brand you want to research. value: brand_url: https://glossier.com limit: 5 include: - description - image_url tier: secondary secondary_next_page: summary: Secondary products — next page description: >- Multiple products can be primary. Unfiltered results also include products whose relationship is unset; non-products are excluded. Replace cursor with next_cursor from the preceding response for this same brand and tier filter. Continue while has_more is true, even if products is empty. value: brand_url: https://glossier.com limit: 5 include: - description - image_url tier: secondary cursor: REPLACE_WITH_NEXT_CURSOR required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/BrandProductResponse' '404': description: No results found for the given brand or product. content: application/json: example: detail: No products found on https://example.com '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyHeader: [] components: schemas: BrandProductInput: properties: brand_url: type: string title: Brand Url description: >- Required. Brand website URL to research for products. HTTP URLs are upgraded to HTTPS. Provide this on every request, including pagination requests that also send a `cursor`. example: https://glossier.com brand_name: anyOf: - type: string - type: 'null' title: Brand Name description: >- Deprecated — brand name is now resolved automatically from the URL. This field is accepted but ignored. deprecated: true response_format: $ref: '#/components/schemas/ResponseFormat' description: >- Format for the response: 'json' for structured data, 'text' for natural language default: json example: json cursor: anyOf: - type: string - type: 'null' title: Cursor description: >- Use this to paginate through results, providing the `next_cursor` returned from a previous request. When set, `brand_url` is still required and must match the brand encoded in the cursor. If omitted, the first page of results is returned. tier: anyOf: - type: string enum: - primary - secondary - type: 'null' title: Tier description: >- Optional product relationship filter: primary is what the business mainly sells or provides; secondary covers complementary or incidental offerings outside its main business. Omit to include all verified products, including those whose relationship cannot be established. Use the same filter on every pagination request. limit: type: integer maximum: 20 minimum: 1 title: Limit description: >- Maximum products to return, from 1 to 20. Fewer may be returned when the website supports fewer offerings. default: 10 include: anyOf: - items: type: string enum: - description - image_url type: array - type: 'null' title: Include description: >- Which per-product fields to return. Allowed values: 'description', 'image_url'. Omit the field to get 'description' only (the default). Add 'image_url' to also get product images. An explicit empty list returns name, url, and tier when known. Unrequested fields are omitted. Example: ["description", "image_url"] type: object required: - brand_url title: BrandProductInput description: Input model for brand product research endpoint. BrandProductResponse: properties: brand_url: type: string title: Brand Url description: The brand's primary website URL example: https://www.glossier.com brand_name: type: string title: Brand Name description: The resolved brand name example: Glossier products: items: $ref: '#/components/schemas/ProductInfo' type: array title: Products description: List of products found on the brand's website next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: Pagination cursor for the next page of results (if available). has_more: anyOf: - type: boolean - type: 'null' title: Has More description: Whether more pages of results are available. example: true effort: $ref: '#/components/schemas/EffortLevel' description: >- Depth actually traveled to produce this page (resolved; never 'auto'). 'low' = served from the catalog/listing with no per-product detail lookups; 'mid'/'high' = a growing share of results needed a detail lookup. default: low example: low type: object required: - brand_url - brand_name - products title: BrandProductResponse description: Response model for brand product research results. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ResponseFormat: type: string enum: - json - text title: ResponseFormat description: Response format options for brand product research. ProductInfo: properties: name: type: string title: Name description: The name of the product examples: - Boy Brow tier: anyOf: - type: string enum: - primary - secondary - type: 'null' title: Tier description: >- Relationship to the business: primary is its main goods or services; secondary is complementary or incidental offerings outside its main business. Omitted when website evidence is insufficient. Several or all products can be primary; this is not a popularity ranking. category: anyOf: - type: string - type: 'null' title: Category description: The category or type of the product examples: - Brows description: anyOf: - type: string - type: 'null' title: Description description: Description of the product examples: - A brushable, buildable brow gel that shapes and fills brows. url: anyOf: - type: string - type: 'null' title: Url description: URL to the product page examples: - https://www.glossier.com/products/boy-brow image_url: anyOf: - type: string - type: 'null' title: Image Url description: URL of the product's primary image, if available. examples: - https://www.glossier.com/cdn/images/boy-brow.jpg type: object required: - name title: ProductInfo description: Product information from brand website. EffortLevel: type: string enum: - auto - low - mid - high title: EffortLevel description: Effort level for product research. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError securitySchemes: APIKeyHeader: type: apiKey in: header name: X-API-Key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.