---
title: "How to retrieve posts using Flowbox's API - v1 (legacy)"
url: "https://kb.getflowbox.com/en/article/how-to-retrieve-posts-using-flowboxs-api"
language: "en"
last_updated: "2026-06-02T08:48:29.546Z"
---

# How to retrieve posts using Flowbox's API - v1 (legacy)

This guide will walk you through the process of retrieving posts from a specific Flow using Flowbox's API.

## Prerequisites

Before you start, ensure you have the following:

-   **API key**: Your unique API authentication key. If you don't have it yet, please contact your CSM and they'll provide it to you.

-   **Flow key**: The unique key identifying the Flow from which you want to retrieve posts. The easiest way to find this is copying it from the "Copy Flow Key" option in the three dot menu, in the Flows section in Flowbox:

![](https://cdn-assets.productfruits.com/0421c4e7-7052-4320-8ee0-0d1afbb41bb6)

## API Endpoint

To retrieve posts from a specific Flow, you need to send a GET request to the following endpoint:

```
https://external-api.getflowbox.com/v1/flow/{flowKey}/posts
```

> You can find more information and make test calls in our [Swaggerhub page](https://app.swaggerhub.com/apis-docs/FlowboxAB/External-API/v1#/External%20API/GetPostsByFlowKey).

## Required Parameters

| Parameter | Type | Location | Description |
| --- | --- | --- | --- |
| `api-key` | string | header | Your API authentication key. Must be included in every request. |
| `flowKey` | string | path | Key of the Flow to retrieve posts from. |
| `locale` | string | query | Locale of the products to be returned. Must match the locale of one of your catalogs. Use lowercase format, e.g. `"en-gb"`. |

## Optional Parameters

| Parameter | Type | Location | Description |
| --- | --- | --- | --- |
| `postsPerPage` | integer | query | Number of posts to retrieve per request. Defaults to `29`. Maximum is `58`. |
| `productId`\* | string | query | Product ID to filter posts by. When provided, returns matching posts from all Flows in the account. If omitted, returns posts from the Approved folder of the Flow matching the `flowKey`. |
| `similarProduct` | boolean | query | *This is a premium feature, contact your CSM for more information.* Filters by product tagging type. `true`: posts where the product is tagged as similar. `false`: posts where the product is tagged as exact. Omitted: returns all posts (both exact and similar). |
| `tags`\* | string | query | Comma-separated list of tags to filter posts by. |
| `operator` | string | query | Logical operator for tag filtering. `"AND"` returns posts matching all specified tags. `"OR"` returns posts matching any specified tag. |
| `cursor` | string | query | Cursor string from the previous response, used for pagination. Pass the full `cursor` object returned by the prior request. |

**\*Required depending on** **`type`** **provided.**

## Example API Request

Here is an example request with both required and optional parameters:

```
curl -X 'GET' \  
'https://external-api.getflowbox.com/v1/flow/INSERT_FLOW_KEY_HERE/posts?locale=es-es&postsPerPage=5' \   
-H 'accept: application/json' \   
-H 'api-key: INSERT_API_KEY_HERE'
```

## Response:

The response will be a JSON containing the posts retrieved based on the parameters you provided. Each post will contain data such as product information, associated tags, and other relevant metadata.

### **JSON structure:**

**Root:**

| Field | Type | Description |
| --- | --- | --- |
| `status` | string | Request status. One of: `"success"`, `"error"`. |
| `data.posts` | array | List of post objects. See *Post object* table below. |
| `data.cursor` | object | Cursor for fetching the next page. Pass to the `cursor` query parameter to paginate. See Cursor table below. |

**Post** (object):

| Field | Type | Description |
| --- | --- | --- |
| `postKey` | string | Unique identifier for the post. |
| `flowKey` | string | Key of the Flow the post belongs to. |
| `postPermalink` | string | URL to the post in the Flowbox app. |
| `sourceName` | string | Source platform of the post, e.g. `"instagram"`, `"facebook"`, `"custom"` (uploaded media). |
| `media` | array | List of media objects attached to the post. See *Media object* table below. |
| `publishedAt` | string | ISO 8601 timestamp of when the post was published, e.g. `"2026-02-26T10:27:36.131667+0000"`. |
| `userPermalink` | string | URL to the author's profile on the source platform. `null` for custom posts. |
| `thumbnail.url` | string | URL of the primary thumbnail (`cdn.flbx.io`). |
| `thumbnail.fallbackUrl` | string | Direct S3 URL used if the primary `url` is unavailable. |
| `text` | string | Caption or body text of the post. `null` if no caption was provided. |
| `userName` | string | Handle or username of the post author. |
| `productKeys` | string | JSON-encoded array of exact-matched product keys tagged on the post. Parse before use: `JSON.parse(post.productKeys)`. |
| `comments` | integer | Number of comments on the post. |
| `likes` | integer | Number of likes on the post. |
| `interactions` | integer | Total number of interactions tracked by Flowbox. |

**Media** (object):

| Field | Type | Description |
| --- | --- | --- |
| `type` | string | Media type. One of: `"image"`, `"video".` |
| `url` | string | URL of the media asset (`cdn.flbx.io`). |
| `fallbackUrl` | string | Direct S3 URL used if the primary `url` is unavailable. |
| `thumbnail` | boolean | Whether this media item is the designated thumbnail for the post. |

**Cursor** (object):

| Field | Type | Description |
| --- | --- | --- |
| `feedKey` | string | Key of the feed the cursor is scoped to. Matches the `flowKey` of the returned posts. |
| `key` | string | `postKey` of the last retrieved post. |
| `publishedAt` | string | ISO 8601 timestamp of the last retrieved post. Used for pagination. |
| `tableName` | string | Internal identifier for the data source, e.g. `"approved_posts"`. |