---
title: "Search pins by a given search term"
method: GET
path: "/search/partner/pins"
tags: ["search"]
---

# Search pins by a given search term

`GET /search/partner/pins`

**This endpoint is currently in beta and not available to all apps. [Learn more](/docs/getting-started/using-beta-and-restricted-features/).**

Get the top 10 Pins by a given search term.

## Query parameters

- `term` string, required
- `country_code` string, required
- `bookmark` string
- `locale` string
- `limit` integer

## Response `200`

The request has succeeded.

- object
  - `bookmark` string, nullable
  - `items` SummaryPin[], required
    - `alt_text` string, nullable
    - `description` string, nullable
    - `id` string, required
    - `link` string, nullable
    - `media` union — Pin media that can be an image, video, or a mix of both.
      - object — Pin with image.
        - `images` ImageSize
          - `1200x` ImageDetails
            - `height` integer, nullable, required
            - `url` string, required
            - `width` integer, nullable, required
          - `150x150` ImageDetails
            - `height` integer, nullable, required
            - `url` string, required
            - `width` integer, nullable, required
          - `400x300` ImageDetails
            - `height` integer, nullable, required
            - `url` string, required
            - `width` integer, nullable, required
          - `600x` ImageDetails
            - `height` integer, nullable, required
            - `url` string, required
            - `width` integer, nullable, required
        - `media_type` 'image', required
      - object — Pin with video.
        - `cover_image_url` string
        - `duration` number, nullable — Duration (in miliseconds). Field maybe null after creation due to video processing time.
        - `height` integer, nullable — Height (in pixels). Field maybe null after creation due to video processing time.
        - `images` ImageSize
          - `1200x` ImageDetails
            - `height` integer, nullable, required
            - `url` string, required
            - `width` integer, nullable, required
          - `150x150` ImageDetails
            - `height` integer, nullable, required
            - `url` string, required
            - `width` integer, nullable, required
          - `400x300` ImageDetails
            - `height` integer, nullable, required
            - `url` string, required
            - `width` integer, nullable, required
          - `600x` ImageDetails
            - `height` integer, nullable, required
            - `url` string, required
            - `width` integer, nullable, required
        - `media_type` 'video', required
        - `video_url` string, nullable — Video url (720p). **Note:** This field is limited and not available to all apps.
        - `video_url_hls` string, nullable — Video url (HLS). **Note:** This field is limited and not available to all apps.
        - `width` integer, nullable — Width (in pixels). Field maybe null after creation due to video processing time.
      - object — Pin with multiple images.
        - `items` ImageMetadata[]
          - `description` string, nullable
          - `images` ImageSize
            - `1200x` ImageDetails
              - …
            - `150x150` ImageDetails
              - …
            - `400x300` ImageDetails
              - …
            - `600x` ImageDetails
              - …
          - `item_type` 'image', required — Discriminator literal identifying this as image metadata inside a `PinMediaMetadata` payload.
          - `link` string, nullable
          - `title` string, nullable
        - `media_type` 'multiple_images', required
      - object — Pin with multiple videos.
        - `items` VideoMetadataWithItemType[]
          - `cover_image_url` string
          - `duration` number, nullable — Duration (in miliseconds). Field maybe null after creation due to video processing time.
          - `height` integer, nullable — Height (in pixels). Field maybe null after creation due to video processing time.
          - `item_type` 'video', required — Discriminator literal identifying this as video metadata inside a `PinMediaMetadata` payload.
          - `video_url` string, nullable — Video url (720p). **Note:** This field is limited and not available to all apps.
          - `video_url_hls` string, nullable — Video url (HLS). **Note:** This field is limited and not available to all apps.
          - `width` integer, nullable — Width (in pixels). Field maybe null after creation due to video processing time.
        - `media_type` 'multiple_videos', required
      - object — Pin with a mix of images and videos.
        - `items` PinMediaMetadata[]
          - union — Per-item entry inside `PinMedia.items` for mixed image/video pins. Discriminated by `item_type`.
            - object
              - …
            - object
              - …
        - `media_type` 'multiple_mixed', required
    - `title` string, nullable

## Other responses

- `400` — The request could not be understood by the server due to unexpected data.
- `401` — Authentication is required and has either failed or not been provided.
- `403` — The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource.
- `404` — The requested resource could not be found on this server.
- `429` — The user has sent too many requests in a given amount of time and is being rate limited.
- `default` — An unexpected error response.

## Changes

- **2026-06-04** (v5) `b698c180678a` — 1 breaking, 7 info
  - the response's body type changed from no type to `object` for status `200`
  - removed `#/components/schemas/Paginated, subschema #2` from the response body `allOf` list for the response status `200`
  - added the non-success response with the status `401`
  - added the non-success response with the status `403`
  - …4 more
- **2025-08-14** (v5) `7d64d863909a` — 1 breaking, 2 info
  - added `#/components/schemas/PinMediaWithImage, #/components/schemas/PinMediaWithVideo, #/components/schemas/PinMediaWithImages, #/components/schemas/PinMediaWithVideos, #/components/schemas/PinMediaWithImageAndVideo` to the `allOf[subschema #2]/items/items/media/allOf[subschema #1: Pin media -> subschema #1: Pin media response object.]/` response property `oneOf` list for the response status `200`
  - removed `#/components/schemas/PinMediaBase, subschema #2` from the `allOf[subschema #2]/items/items/media/allOf[subschema #1: Pin media -> subschema #1: Pin media response object.]/` response property `allOf` list for the response status `200`
  - added discriminator to `allOf[subschema #2]/items/items/media/allOf[subschema #1: Pin media -> subschema #1: Pin media response object.]/` response property for the response status `200`
- …earlier changes not shown

[Full history](https://skmtc.dev/pinterest/apis/pinterest-rest-api/changes/search/partner/pins/get.md)

---

[API](https://skmtc.dev/pinterest/apis/pinterest-rest-api.md) · [All operations](https://skmtc.dev/pinterest/apis/pinterest-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/pinterest/pinterest-rest-api/revisions/b698c180678a/schema)