# List posts

> Returns approved posts that match the requested filters.

Breadcrumb: Storefront API › List posts
Docs index: https://docs.cevoid.com/developers/llms.txt

`GET https://api.widget.cevoid.com/v1/posts`

Returns approved posts that match the requested filters.

## Authorizations

Bearer token in the Authorization header: `Authorization: Bearer <key>` (Cevoid publishable key).

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `market` | `string` | Yes | Market identifier used for localized product data. Length: `1 to 256`. Example: `mar_sweden`. |
| `profile_id` | `string` | No | Return posts attributed to this profile. Length: `1 to 256`. Example: `prf_jane`. |
| `label_id` | `string[]` | No | Return posts with these labels. Repeat the parameter to provide more than one label. Items: `1 to 50`. Each item: length: `1 to 256`. Example: `["lbl_summer","lbl_featured"]`. |
| `label_match` | `enum<string>` | No | Match any requested label (default) or require all requested labels. Requires label_id. Unknown labels are ignored for any; all returns no posts if any label is unknown. If no labels resolve, no posts are returned. Allowed values: `any`, `all`. Example: `any`. |
| `gallery_id` | `string` | No | Return posts selected by this published gallery, newest first. Applies gallery filters but not pinned layout order. Length: `1 to 256`. Example: `gal_summer`. |
| `product_ref` | `string` | No | A Cevoid product or variant ID, provider-native ID, SKU, or barcode. Resolves within this workspace and market and selects the product family, including variants and existing tags. Unknown, ambiguous, or more than 100 candidate matches return an empty page; use a Cevoid product ID to disambiguate. Families with more than 1,000 product records return 400 with product_too_broad. Length: `1 to 256`. Example: `gid://shopify/Product/123`. |
| `external_collection_id` | `string` | No | Return posts containing products in this market-specific external collection. Length: `1 to 256`. Example: `summer-sale`. |
| `cursor` | `string` | No | Opaque cursor returned by the previous page. Keep all other query parameters unchanged. Length: `1 to 2048`. Example: `eyJjcmVhdGVkQXQiOiIyMDI2LTA4LTAxVDEwOjAwOjAwLjAwMFoifQ`. |
| `limit` | `integer` | No | Number of posts to return, from 1 to 50. Default: `20`. Range: `1 <= x <= 50`. Example: `20`. |

## Response

### 200: Successful response

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | `object[]` | Yes |  |
| `data[].id` | `string` | Yes | Stable public Post identifier. Length: `1 to 256`. Example: `pst_summerlook`. |
| `data[].type` | `enum<string>` | Yes | Post media type. Allowed values: `IMAGE`, `VIDEO`. Example: `IMAGE`. |
| `data[].media` | `object` | Yes |  |
| `data[].media.url` | `string<uri>` | Yes | CDN URL for the post media. Example: `https://cdn.cevoid.com/posts/pst_summerlook.jpg`. |
| `data[].media.thumbnail_url` | `string<uri>` | No | Smaller preview image when available. Example: `https://cdn.cevoid.com/posts/pst_summerlook-thumbnail.jpg`. |
| `data[].media.sprite_url` | `string<uri>` | No | Video sprite image for timeline previews when available. Example: `https://cdn.cevoid.com/posts/pst_summerlook-sprite.jpg`. |
| `data[].media.blurhash` | `string` | No | BlurHash placeholder for the media asset. Example: `LEHV6nWB2yk8pyo0adR*.7kCMdnj`. |
| `data[].media.aspect_ratio` | `number` | No | Media width divided by height. Range: `0 < x`. Example: `0.8`. |
| `data[].media.duration_seconds` | `number` | No | Video duration in seconds. Range: `0 <= x`. Example: `12.5`. |
| `data[].media.has_audio` | `boolean` | No | Whether video media includes an audio track. Example: `true`. |
| `data[].caption` | `string` | No | Public post caption. Omitted when hide_caption is true. Example: `A summer favorite.`. |
| `data[].hide_caption` | `boolean` | Yes | Whether clients should hide the caption. Example: `false`. |
| `data[].alt` | `string` | No | Accessible media description. Example: `Person wearing a beige linen shirt outdoors.`. |
| `data[].video_captions` | `string` | No | WebVTT captions for video media. Example: `WEBVTT

00:00.000 --> 00:02.000
A summer favorite.`. |
| `data[].video_description` | `string` | No | Accessible description of video content. Example: `A person turns to show the front and back of a linen shirt.`. |
| `data[].source_url` | `string<uri>` | No | Original public social post URL when available. Example: `https://www.instagram.com/p/example/`. |
| `data[].author` | `object` | No |  |
| `data[].author.name` | `string` | Yes | Public display name selected for the storefront. Example: `@jane`. |
| `data[].author.avatar_url` | `string<uri>` | No | Public profile image URL when available. Example: `https://cdn.cevoid.com/profiles/prf_jane.jpg`. |
| `data[].custom_link` | `object` | No | Editorial link attached to this post. |
| `data[].custom_link.url` | `string<uri>` | Yes | Example: `https://shop.example.com/stories/summer`. |
| `data[].custom_link.title` | `string` | No | Example: `Summer stories`. |
| `data[].custom_link.description` | `string` | No | Example: `Explore our summer stories.`. |
| `data[].custom_link.image_url` | `string<uri>` | No | Example: `https://cdn.cevoid.com/stories/summer.jpg`. |
| `data[].tagged_products` | `object[]` | Yes | Shoppable products in the selected market. Products without a presentation in that market are omitted. |
| `data[].tagged_products[].id` | `string` | Yes | Stable public Product identifier. Length: `1 to 256`. Example: `prd_linen_shirt`. |
| `data[].tagged_products[].title` | `string` | Yes | Market-specific product title. Example: `Linen Shirt`. |
| `data[].tagged_products[].type` | `enum<string>` | Yes | Allowed values: `PRODUCT`, `VARIANT`. Example: `PRODUCT`. |
| `data[].tagged_products[].parent_product_id` | `string` | No | Length: `1 to 256`. Example: `prd_linen_shirt`. |
| `data[].tagged_products[].availability` | `enum<string>` | No | Allowed values: `IN_STOCK`, `OUT_OF_STOCK`. Example: `IN_STOCK`. |
| `data[].tagged_products[].url` | `string<uri>` | No | Market-specific storefront URL. Example: `https://shop.example.com/products/linen-shirt`. |
| `data[].tagged_products[].image_url` | `string<uri>` | No | Market-specific product image URL. Example: `https://cdn.cevoid.com/products/linen-shirt.jpg`. |
| `data[].tagged_products[].price` | `object` | No | Product price range or exact variant price in the selected market. Omitted when the market hides prices. |
| `data[].tagged_products[].price.currency` | `string` | Yes |  |
| `data[].tagged_products[].price.min_amount` | `number` | Yes | Range: `0 <= x`. |
| `data[].tagged_products[].price.max_amount` | `number` | Yes | Range: `0 <= x`. |
| `data[].tagged_products[].price.currency` | `string` | Yes |  |
| `data[].tagged_products[].price.amount` | `number` | Yes | Range: `0 <= x`. |
| `data[].tagged_products[].price.sale_amount` | `number` | No | Range: `0 <= x`. |
| `data[].tagged_products[].x` | `number` | No | Normalized horizontal hotspot position. Omitted together with y when no valid position is stored. Range: `0 <= x <= 1`. Example: `0.35`. |
| `data[].tagged_products[].y` | `number` | No | Normalized vertical hotspot position. Range: `0 <= x <= 1`. Example: `0.65`. |
| `data[].published_at` | `string<date-time>` | Yes | Creation time in Cevoid, used for newest-first ordering. This can differ from the original social publication date. Example: `2026-08-01T10:00:00.000Z`. |
| `has_more` | `boolean` | Yes | Whether another page is available. Example: `true`. |
| `next_cursor` | `string \| null` | Yes | Opaque cursor for the next page, or null when this is the final page. Example: `eyJwdWJsaXNoZWRBdCI6IjIwMjYtMDgtMDFUMTA6MDA6MDAuMDAwWiJ9`. |

Response headers:

| Header | Type | Description |
| --- | --- | --- |
| `Cevoid-Processing-Ms` | `string` | End-to-end request processing time in milliseconds |
| `Cevoid-Request-Id` | `string` | Request identifier for support and tracing |
| `RateLimit-Limit` | `string` | Current rate limit bucket size |
| `RateLimit-Remaining` | `string` | Remaining requests in the current rate limit window |
| `RateLimit-Reset` | `integer` | Seconds until the next request token is available |
| `Cache-Control` | `string` | Browser freshness is 60 seconds. Shared caches are fresh for five minutes and may serve stale content while revalidating for another five minutes. TTL is the only invalidation guarantee; moderation or removal may take up to ten minutes because no active purge is performed. |
| `Vary` | `string` | Workspace credential headers included in the shared-cache key. |

```json
{
  "data": [
    {
      "id": "pst_summerlook",
      "type": "IMAGE",
      "media": {
        "url": "https://cdn.cevoid.com/posts/pst_summerlook.jpg",
        "thumbnail_url": "https://cdn.cevoid.com/posts/pst_summerlook-thumbnail.jpg",
        "sprite_url": "https://cdn.cevoid.com/posts/pst_summerlook-sprite.jpg",
        "blurhash": "LEHV6nWB2yk8pyo0adR*.7kCMdnj",
        "aspect_ratio": 0.8,
        "duration_seconds": 12.5,
        "has_audio": false
      },
      "caption": "A summer favorite.",
      "hide_caption": false,
      "alt": "Person wearing a beige linen shirt outdoors.",
      "source_url": "https://www.instagram.com/p/example/",
      "author": {
        "name": "@jane",
        "avatar_url": "https://cdn.cevoid.com/profiles/prf_jane.jpg"
      },
      "tagged_products": [
        {
          "id": "prd_linen_shirt",
          "type": "PRODUCT",
          "title": "Linen Shirt",
          "url": "https://shop.example.com/products/linen-shirt",
          "image_url": "https://cdn.cevoid.com/products/linen-shirt.jpg",
          "price": {
            "min_amount": 59.95,
            "max_amount": 79.95,
            "currency": "SEK"
          },
          "x": 0.35,
          "y": 0.65
        }
      ],
      "published_at": "2026-08-01T10:00:00.000Z"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJwdWJsaXNoZWRBdCI6IjIwMjYtMDgtMDFUMTA6MDA6MDAuMDAwWiJ9"
}
```

### 400: Bad request

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `additional_data` | `object` | No | Optional machine-readable error details. |
| `additional_data.{key}` | `any \| null` | No |  |
| `status` | `integer` | Yes | HTTP status code. Example: `404`. |
| `code` | `string` | Yes | Stable machine-readable error code. Example: `not_found`. |
| `message` | `string` | Yes | Human-readable error description. Example: `Resource not found`. |
| `request_id` | `string` | No | Request identifier for support and tracing. Example: `req_abc123`. |

Response headers:

| Header | Type | Description |
| --- | --- | --- |
| `Cevoid-Processing-Ms` | `string` | End-to-end request processing time in milliseconds |
| `Cevoid-Request-Id` | `string` | Request identifier for support and tracing |
| `RateLimit-Limit` | `string` | Current rate limit bucket size |
| `RateLimit-Remaining` | `string` | Remaining requests in the current rate limit window |
| `RateLimit-Reset` | `integer` | Seconds until the next request token is available |

```json
{
  "additional_data": {
    "property1": null,
    "property2": null
  },
  "status": 400,
  "code": "bad_request",
  "message": "Bad request",
  "request_id": "req_abc123"
}
```

### 401: Unauthorized

`application/json`

Same fields as 400.

Response headers: the same as 400.

```json
{
  "status": 401,
  "code": "unauthorized",
  "message": "Unauthorized",
  "request_id": "req_abc123"
}
```

### 403: Forbidden

`application/json`

Same fields as 400.

Response headers: the same as 400.

```json
{
  "status": 403,
  "code": "forbidden",
  "message": "Forbidden",
  "request_id": "req_abc123"
}
```

### 404: Not found

`application/json`

Same fields as 400.

Response headers: the same as 400.

```json
{
  "additional_data": {
    "property1": null,
    "property2": null
  },
  "status": 404,
  "code": "not_found",
  "message": "Resource not found",
  "request_id": "req_abc123"
}
```

### 422: Validation error

`application/json`

Same fields as 400.

Response headers: the same as 400.

```json
{
  "additional_data": {
    "property1": null,
    "property2": null
  },
  "status": 422,
  "code": "validation_error",
  "message": "Validation error",
  "request_id": "req_abc123"
}
```

### 429: Too many requests

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `additional_data` | `object` | Yes | Machine-readable rate-limit details. |
| `additional_data.retry_after_seconds` | `integer` | Yes | Range: `0 <= x`. |
| `additional_data.{key}` | `any \| null` | No |  |
| `status` | `integer` | Yes | HTTP status code. Example: `404`. |
| `code` | `string` | Yes | Stable machine-readable error code. Example: `not_found`. |
| `message` | `string` | Yes | Human-readable error description. Example: `Resource not found`. |
| `request_id` | `string` | No | Request identifier for support and tracing. Example: `req_abc123`. |

Response headers:

| Header | Type | Description |
| --- | --- | --- |
| `Cevoid-Processing-Ms` | `string` | End-to-end request processing time in milliseconds |
| `Cevoid-Request-Id` | `string` | Request identifier for support and tracing |
| `RateLimit-Limit` | `string` | Current rate limit bucket size |
| `RateLimit-Remaining` | `string` | Remaining requests in the current rate limit window |
| `RateLimit-Reset` | `integer` | Seconds until the next request token is available |
| `Retry-After` | `integer` | Seconds to wait before retrying the request |

```json
{
  "status": 429,
  "code": "rate_limit_exceeded",
  "message": "Rate limit exceeded",
  "request_id": "req_abc123",
  "additional_data": {
    "retry_after_seconds": 1
  }
}
```

### 500: Internal server error

`application/json`

Same fields as 400.

Response headers: the same as 400.

```json
{
  "status": 500,
  "code": "internal_server_error",
  "message": "Internal server error",
  "request_id": "req_abc123"
}
```

### 503: Service unavailable

`application/json`

Same fields as 400.

Response headers: the same as 400.

```json
{
  "status": 503,
  "code": "service_unavailable",
  "message": "Service unavailable",
  "request_id": "req_abc123"
}
```

## Request example

```bash
curl 'https://api.widget.cevoid.com/v1/posts?market=mar_sweden' \
  -H "Authorization: Bearer ${CEVOID_PUBLISHABLE_KEY}"
```

---

Canonical: https://docs.cevoid.com/developers/storefront-api/storefront-ugc/list-posts