---
updatedAt: 2026-10-29T11:54:48.000Z
agentTools:
  projectIndex: https://docs.yotpo.com/llms.txt
---

# Photos by album

Fetches the custom album payload including album images, tags, names, and ID's of all existing custom albums per account `app_key`.
For Instagram media, the `post` object includes `post_id` and `post_link`. Use `post_id` to group media from the same Instagram post. For older media, `post_id` is `null`, so use `post_link` for grouping instead.

> 👍 How to use this endpoint
>
> * For example responses, click the relevant status code on the right.

> 📘 Instagram media
>
> For Instagram media, the `post` object includes `post_id` and `post_link`. Use `post_id` to group media from the same Instagram post. For older media, `post_id` is `null`, so group by `post_link` instead.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Reviews API (V1)",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://api.yotpo.com",
      "description": "Main API server for authenticated and write operations"
    }
  ],
  "components": {
    "securitySchemes": {
      "X-Yotpo-Token": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Yotpo-Token",
        "description": "Your Yotpo account access token. See [Yotpo Authentication](ref:yotpo-authentication) to learn how to generate your token."
      }
    }
  },
  "security": [
    {
      "X-Yotpo-Token": []
    }
  ],
  "paths": {
    "/v1/widget/{store_id}/albums/by_name": {
      "get": {
        "summary": "Photos by album",
        "description": "Fetches the custom album payload including album images, tags, names, and ID's of all existing custom albums per account `store_id`.\n\nFor Instagram media, the `post` object includes `post_id` and `post_link`. Use `post_id` to group media from the same Instagram post. For older media, `post_id` is `null`, so use `post_link` for grouping instead.",
        "operationId": "photos-by-album",
        "parameters": [
          {
            "name": "album_name",
            "in": "query",
            "description": "The name of your custom album. The album name can be found by using the <a href=\"/reference/get-custom-albums\" target=\"_blank\">Custom albums</a> endpoint.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "The page number of a paginated response. Must be greater than zero. Default: 1",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 1
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "description": "The number of results to return per page. Maximum 56 per page.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "store_id",
            "in": "path",
            "description": "The store ID",
            "schema": {
              "type": "string"
            },
            "required": true
          },
          {
            "name": "favorite",
            "in": "query",
            "description": "Set to `true` to return only starred images or `false` for only unstarred images. Omit to return both. If the album has no starred images, `true` returns `404 Album not found`.",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n  \"status\": {\n    \"code\": 200,\n    \"message\": \"OK\"\n  },\n  \"response\": {\n    \"pagination\": {\n      \"page\": 1,\n      \"per_page\": 3,\n      \"total\": 0\n    },\n    \"images\": [\n      {\n        \"source\": \"instagram\",\n        \"image_id\": \"5a98197f6efb092db231f695\",\n        \"low_resolution_image_url\": \"//scontent.cdninstagram.com/vp/da9f5101451fa862caabf874716755f6/5B2B50AF/t51.2885-15/e35/p320x320/28156507_165346500940639_6306343443274661888_n.jpg\",\n        \"original_image_url\": \"//scontent.cdninstagram.com/vp/88cae9a00ac8b10265bd97b7d5ef1159/5B3ECDF8/t51.2885-15/sh0.08/e35/p640x640/28156507_165346500940639_6306343443274661888_n.jpg\",\n        \"image_url\": \"//scontent.cdninstagram.com/vp/c26ee077c49ceb4567d77ff073439d4e/5B37EEA0/t51.2885-15/s150x150/e35/c0.43.1080.1080/28156507_165346500940639_6306343443274661888_n.jpg\",\n        \"medium_image_url\": \"//cdn-yotpo-images-production.yotpo.com/Review/208866404/141437668/medium.jpg?1603967988\",\n        \"external_media_id\": \"1724914648462926403_3220168402\",\n        \"tagged_products\": [\n          {\n            \"id\": 23626625,\n            \"name\": \"Classy Signature T-Shirt\",\n            \"domain_key\": \"6\",\n            \"product_link\": \"https://yotpos-demo-store-2.myshopify.com/products/classy-signature\",\n            \"product_url\": \"https://yotpos-demo-store-2.myshopify.com/products/classy-signature\",\n            \"image_url\": \"https://ddcfq0gxiontw.cloudfront.net/Product/23827964/18687703/square.jpg?1499177861\",\n            \"score\": null,\n            \"reviews_count\": null\n          }\n        ],\n        \"media_type\": \"image\",\n        \"permission_request_status\": \"approved\",\n        \"post\": {\n          \"profile_picture\": \"https://scontent.cdninstagram.com/vp/ad77096025c93ac62127bc4788dd5350/5B35AAB4/t51.2885-19/s150x150/18879688_1351838138239441_1502256565162344448_a.jpg\",\n          \"username\": \"dey_ag1112\",\n          \"location_name\": \"\",\n          \"created_time\": \"2018-02-28T19:24:31.000+00:00\",\n          \"hashtags\": [\n            \"spicyblackbeanburger\",\n            \"lemon\",\n            \"terradelyssa\",\n            \"saladfordays\",\n            \"lunchtime\",\n            \"himalayansalt\",\n            \"homemadedressing\",\n            \"morningstarfarms\",\n            \"oliveoil\"\n          ],\n          \"content\": \"🍴\\n#lunchtime #saladfordays #morningstarfarms #spicyblackbeanburger #homemadedressing #oliveoil #lemon #himalayansalt #terradelyssa\",\n          \"votes_up\": 0,\n          \"votes_down\": 0,\n          \"post_id\": \"18023257757718362\",\n          \"post_link\": \"https://www.instagram.com/p/DebdrjIDrrv/\"\n        }\n      },\n      {\n        \"source\": \"review\",\n        \"image_id\": \"29087960\",\n        \"review_id\": 48902637,\n        \"low_resolution_image_url\": \"//ddcfq0gxiontw.cloudfront.net/Review/48902637/29087960/medium_square.jpg?1511673183\",\n        \"image_url\": \"//ddcfq0gxiontw.cloudfront.net/Review/48902637/29087960/square.jpg?1511673183\",\n        \"original_image_url\": \"//ddcfq0gxiontw.cloudfront.net/Review/48902637/29087960/original.jpg?1511673183\",\n        \"medium_image_url\": \"//cdn-yotpo-images-production.yotpo.com/Review/208866404/141437668/medium.jpg?1603967988\",\n        \"review\": {\n          \"id\": 48902637,\n          \"review_type_id\": 1,\n          \"rejected\": false,\n          \"title\": \"Excellent\",\n          \"content\": \"Thank you I love them\",\n          \"score\": 5,\n          \"created_at\": \"2017-11-26T05:13:05.000Z\",\n          \"verified_buyer\": 1,\n          \"archived\": 0,\n          \"deleted\": 0,\n          \"votes_up\": 0,\n          \"votes_down\": 0,\n          \"user\": {\n            \"display_name\": \"renee\",\n            \"social_image\": null,\n            \"email\": \"renee_40057171-470c-47d8-abed-6fe8a63e84ba@example.com\"\n          }\n        },\n        \"product\": {\n          \"domain_key\": \"1\",\n          \"name\": \"Crewneck Pocket T-Shirt\",\n          \"product_url\": \"https://yotpos-demo-store-2.myshopify.com/products/crewneck-pocket\",\n          \"product_link\": \"https://yotpos-demo-store-2.myshopify.com/products/crewneck-pocket\",\n          \"image_url\": \"https://ddcfq0gxiontw.cloudfront.net/Product/23827969/18687695/square.jpg?1499177859\"\n        }\n      },\n      {\n        \"source\": \"instagram\",\n        \"image_id\": \"59f73c3b3fa5a35e927847ae\",\n        \"low_resolution_image_url\": \"//scontent.cdninstagram.com/vp/b4fbe8dc582627cd755d961533559c7b/5B4EB108/t51.2885-15/s320x320/e35/22860435_1627650820618673_6136770394897514496_n.jpg\",\n        \"original_image_url\": \"//scontent.cdninstagram.com/vp/af4b4d91706d4f7e4ac281c8c8c6884e/5B544D45/t51.2885-15/s640x640/sh0.08/e35/22860435_1627650820618673_6136770394897514496_n.jpg\",\n        \"image_url\": \"//scontent.cdninstagram.com/vp/9a1be59c71d9258922e947ff484c3f4a/5B6FD538/t51.2885-15/s150x150/e35/22860435_1627650820618673_6136770394897514496_n.jpg\",\n        \"medium_image_url\": \"//cdn-yotpo-images-production.yotpo.com/Review/208866404/141437668/medium.jpg?1603967988\",\n        \"external_media_id\": \"1636642758793837508_4065356078\",\n        \"tagged_products\": [],\n        \"media_type\": \"image\",\n        \"permission_request_status\": \"approved\",\n        \"post\": {\n          \"profile_picture\": \"https://scontent.cdninstagram.com/vp/d2a9ff0d24c73924ed59ef664b0a9082/5B397663/t51.2885-19/s150x150/14717358_368701900129822_7310002550739042304_a.jpg\",\n          \"username\": \"boz_rich\",\n          \"location_name\": \"\",\n          \"created_time\": \"2017-10-30T00:24:02.000+00:00\",\n          \"hashtags\": [\n            \"wornandwound\",\n            \"danhenrywatches\",\n            \"windupnyc\"\n          ],\n          \"content\": \"Not too crazy about quartz these days but if there is ever a quartz to have in my collection, this is the one. Enter the Dan Henry Multiscale Chronograph 1939. Saw this at Wind-up Watch Fair today. And yes I will get this soon. @danhenrywatches @wornandwound  #danhenrywatches #windupnyc #wornandwound\",\n          \"votes_up\": 0,\n          \"votes_down\": 0,\n          \"post_id\": null,\n          \"post_link\": \"https://www.instagram.com/p/DdUs6gaE1Jk/\"\n        }\n      }\n    ]\n  }\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "integer",
                          "example": 200,
                          "default": 0,
                          "description": "HTTP status code."
                        },
                        "message": {
                          "type": "string",
                          "example": "OK",
                          "description": "Status message, for example `OK`."
                        }
                      },
                      "description": "Request status."
                    },
                    "response": {
                      "type": "object",
                      "properties": {
                        "pagination": {
                          "type": "object",
                          "properties": {
                            "page": {
                              "type": "integer",
                              "example": 1,
                              "default": 0,
                              "description": "Current page number."
                            },
                            "per_page": {
                              "type": "integer",
                              "example": 3,
                              "default": 0,
                              "description": "Number of images per page."
                            },
                            "total": {
                              "type": "integer",
                              "example": 0,
                              "default": 0,
                              "description": "Total number of images across all pages."
                            }
                          },
                          "description": "Paging details."
                        },
                        "images": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "source": {
                                "type": "string",
                                "example": "instagram",
                                "description": "Where the media came from, for example `instagram`."
                              },
                              "image_id": {
                                "type": "string",
                                "example": "5a98197f6efb092db231f695",
                                "description": "Yotpo media ID."
                              },
                              "low_resolution_image_url": {
                                "type": "string",
                                "example": "//scontent.cdninstagram.com/vp/da9f5101451fa862caabf874716755f6/5B2B50AF/t51.2885-15/e35/p320x320/28156507_165346500940639_6306343443274661888_n.jpg",
                                "description": "Low-resolution image URL. Protocol-relative (starts with `//`), so add `https:` before using it."
                              },
                              "original_image_url": {
                                "type": "string",
                                "example": "//scontent.cdninstagram.com/vp/88cae9a00ac8b10265bd97b7d5ef1159/5B3ECDF8/t51.2885-15/sh0.08/e35/p640x640/28156507_165346500940639_6306343443274661888_n.jpg",
                                "description": "Full-size (standard resolution) image URL. Protocol-relative (starts with `//`), so add `https:` before using it."
                              },
                              "image_url": {
                                "type": "string",
                                "example": "//scontent.cdninstagram.com/vp/c26ee077c49ceb4567d77ff073439d4e/5B37EEA0/t51.2885-15/s150x150/e35/c0.43.1080.1080/28156507_165346500940639_6306343443274661888_n.jpg",
                                "description": "Thumbnail image URL. Protocol-relative (starts with `//`), so add `https:` before using it."
                              },
                              "medium_image_url": {
                                "type": "string",
                                "example": "//cdn-yotpo-images-production.yotpo.com/Review/208866404/141437668/medium.jpg?1603967988",
                                "description": "Medium-size image URL. Protocol-relative (starts with `//`), so add `https:` before using it."
                              },
                              "external_media_id": {
                                "type": "string",
                                "example": "1724914648462926403_3220168402",
                                "description": "The media's ID on the source platform, for example the Instagram media ID."
                              },
                              "tagged_products": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "id": {
                                      "type": "integer",
                                      "example": 23626625,
                                      "default": 0,
                                      "description": "Yotpo product ID."
                                    },
                                    "name": {
                                      "type": "string",
                                      "example": "Classy Signature T-Shirt",
                                      "description": "Product name."
                                    },
                                    "domain_key": {
                                      "type": "string",
                                      "example": "6",
                                      "description": "Your product ID (the external product ID your store sends to Yotpo)."
                                    },
                                    "product_link": {
                                      "type": "string",
                                      "example": "https://yotpos-demo-store-2.myshopify.com/products/classy-signature",
                                      "description": "Product page URL."
                                    },
                                    "product_url": {
                                      "type": "string",
                                      "example": "https://yotpos-demo-store-2.myshopify.com/products/classy-signature",
                                      "description": "Product page URL."
                                    },
                                    "image_url": {
                                      "type": "string",
                                      "example": "https://ddcfq0gxiontw.cloudfront.net/Product/23827964/18687703/square.jpg?1499177861",
                                      "description": "Product image URL."
                                    },
                                    "score": {},
                                    "reviews_count": {}
                                  }
                                },
                                "description": "Products tagged in this media."
                              },
                              "media_type": {
                                "type": "string",
                                "example": "image",
                                "description": "Media type, for example `image` or `carousel`."
                              },
                              "permission_request_status": {
                                "type": "string",
                                "example": "approved"
                              },
                              "post": {
                                "type": "object",
                                "properties": {
                                  "profile_picture": {
                                    "type": "string",
                                    "example": "https://scontent.cdninstagram.com/vp/ad77096025c93ac62127bc4788dd5350/5B35AAB4/t51.2885-19/s150x150/18879688_1351838138239441_1502256565162344448_a.jpg",
                                    "description": "Profile image URL of the account that posted, or `null`."
                                  },
                                  "username": {
                                    "type": "string",
                                    "example": "dey_ag1112",
                                    "description": "Username of the account that posted."
                                  },
                                  "location_name": {
                                    "type": "string",
                                    "example": "",
                                    "description": "Location tagged on the post, or `null`."
                                  },
                                  "created_time": {
                                    "type": "string",
                                    "example": "2018-02-28T19:24:31.000+00:00",
                                    "description": "When the post was published (ISO 8601)."
                                  },
                                  "hashtags": {
                                    "type": "array",
                                    "items": {
                                      "type": "string",
                                      "example": "spicyblackbeanburger"
                                    },
                                    "description": "Hashtags in the post, without the `#`."
                                  },
                                  "content": {
                                    "type": "string",
                                    "example": "🍴\n#lunchtime #saladfordays #morningstarfarms #spicyblackbeanburger #homemadedressing #oliveoil #lemon #himalayansalt #terradelyssa",
                                    "description": "The post's caption."
                                  },
                                  "votes_up": {
                                    "type": "integer",
                                    "example": 0,
                                    "default": 0,
                                    "description": "Number of helpful (up) votes on the media."
                                  },
                                  "votes_down": {
                                    "type": "integer",
                                    "example": 0,
                                    "default": 0,
                                    "description": "Number of unhelpful (down) votes on the media."
                                  },
                                  "post_id": {
                                    "type": "string",
                                    "nullable": true,
                                    "description": "Instagram media only. The ID of the Instagram post. Shared by all media from the same carousel post. null for older media - use post_link for grouping instead.",
                                    "example": "18023257757718362"
                                  },
                                  "post_link": {
                                    "type": "string",
                                    "description": "Instagram media only. The permalink of the Instagram post the media belongs to. Shared by all media from the same carousel post. Use it for grouping when post_id is null.",
                                    "example": "https://www.instagram.com/p/DebdrjIDrrv/"
                                  }
                                },
                                "description": "The social post the media came from."
                              },
                              "review_id": {
                                "type": [
                                  "integer",
                                  "null"
                                ],
                                "description": "ID of the review the image was uploaded with, when `source` is `review`."
                              },
                              "review": {
                                "type": [
                                  "object",
                                  "null"
                                ],
                                "description": "The review the image was uploaded with, when `source` is `review`."
                              },
                              "product": {
                                "type": [
                                  "object",
                                  "null"
                                ],
                                "description": "The product the image is tagged to."
                              }
                            }
                          },
                          "description": "Images and videos on this page."
                        }
                      },
                      "description": "Response payload."
                    }
                  }
                }
              }
            },
            "headers": {
              "ratelimit-limit": {
                "description": "The maximum number of requests allowed in the current time window",
                "schema": {
                  "type": "integer"
                }
              },
              "ratelimit-remaining": {
                "description": "The number of requests remaining in the current time window",
                "schema": {
                  "type": "integer"
                }
              },
              "ratelimit-reset": {
                "description": "The time (in seconds) until the rate limit resets",
                "schema": {
                  "type": "integer"
                }
              },
              "x-ratelimit-limit-minute": {
                "description": "The maximum number of requests allowed per minute",
                "schema": {
                  "type": "integer"
                }
              },
              "x-ratelimit-remaining-minute": {
                "description": "The number of requests remaining in the current minute",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "400",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            },
            "headers": {
              "ratelimit-limit": {
                "description": "The maximum number of requests allowed in the current time window",
                "schema": {
                  "type": "integer"
                }
              },
              "ratelimit-remaining": {
                "description": "The number of requests remaining in the current time window",
                "schema": {
                  "type": "integer"
                }
              },
              "ratelimit-reset": {
                "description": "The time (in seconds) until the rate limit resets",
                "schema": {
                  "type": "integer"
                }
              },
              "x-ratelimit-limit-minute": {
                "description": "The maximum number of requests allowed per minute",
                "schema": {
                  "type": "integer"
                }
              },
              "x-ratelimit-remaining-minute": {
                "description": "The number of requests remaining in the current minute",
                "schema": {
                  "type": "integer"
                }
              }
            }
          }
        },
        "deprecated": false,
        "security": []
      }
    }
  },
  "x-readme": {
    "headers": [
      {
        "value": "application/json",
        "key": "Content-Type"
      }
    ],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```

# Sibling pages

* [About Visual UGC](https://docs.yotpo.com/reference/about-visual-ugc.md)
* [Product images](https://docs.yotpo.com/reference/product-images.md)