---
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.

---

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