# Get Posts

**Endpoint:**

```
GET https://app.marketingblocks.ai/api/v1/social-sparks/get-posts
```

***

This endpoint retrieves posts from multiple social media channels (Facebook, Instagram, Twitter, LinkedIn, YouTube, TikTok). You can filter by channels and limit the number of posts returned.

Requires the **`social-read-posts`** permission.

***

### Authentication

**Type:** Bearer Token

```
Authorization: Bearer <token>
```

***

### Request Parameters

| Parameter  | Type    | Required | Description                                                                                                                | Example                                                |
| ---------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| `channels` | string  | yes      | Comma-separated list of channels to fetch posts from. Supported: `facebook, instagram, twitter, linkedin, youtube, tiktok` | `facebook,instagram,twitter`                           |
| `limit`    | integer | no       | Maximum number of posts to return per request. Default varies.                                                             | `5`                                                    |
| status     | string  | no       | Comma-separated list of post statuses to filter by. Allowed values: `scheduled`, `draft`, `queued`, `failed`, `published`. | `scheduled`, `draft`, `queued`, `failed`, `published`. |

***

### Example Request

**cURL**

```bash
curl --location --request GET \
'https://app.marketingblocks.ai/api/v1/social-sparks/get-posts?channels=facebook,instagram,twitter,linkedin,youtube,tiktok&limit=5' \
--header 'Authorization: Bearer <token>'
```

**Plain URL**

```
GET https://app.marketingblocks.ai/api/v1/social-sparks/get-posts?channels=facebook,instagram,twitter,linkedin,youtube,tiktok&limit=5
```

***

### Response Structure

The response is a JSON object with two main keys:

* **`posts` (object):** Contains pagination info and list of posts.
* **`status` (boolean):** Indicates whether the request was successful.

#### Posts Object

| Field            | Type    | Description                                   |
| ---------------- | ------- | --------------------------------------------- |
| `current_page`   | integer | Current page number.                          |
| `data`           | array   | Array of post objects (see below).            |
| `first_page_url` | string  | URL to the first page.                        |
| `from`           | integer | Starting index of results.                    |
| `last_page`      | integer | Last page number.                             |
| `last_page_url`  | string  | URL to the last page.                         |
| `next_page_url`  | string  | URL to the next page (if available).          |
| `path`           | string  | Base path of the request.                     |
| `per_page`       | integer | Number of posts per page.                     |
| `prev_page_url`  | string  | URL to the previous page (or `null` if none). |
| `to`             | integer | Ending index of results.                      |
| `total`          | integer | Total number of posts available.              |

#### Post Object

| Field          | Type    | Description                                      |
| -------------- | ------- | ------------------------------------------------ |
| `post_id`      | integer | Unique ID of the post.                           |
| `channel_type` | string  | The channel type (e.g., `facebook`).             |
| `channel_id`   | string  | Unique identifier for the channel.               |
| `STATUS`       | string  | Status of the post (`published`, `failed`).      |
| `permalink`    | string  | URL link to the post.                            |
| `error`        | string  | Error message (only present if `STATUS=failed`). |

***

### Example Response

```json
{
  "posts": {
    "current_page": 1,
    "data": [
      {
        "post_id": 1246,
        "channel_type": "facebook",
        "channel_id": "254",
        "STATUS": "published",
        "permalink": "https://www.facebook.com/270235986170649/posts/270235986170649_122205223640252453"
      },
      {
        "post_id": 1224,
        "channel_type": "twitter",
        "channel_id": "249",
        "STATUS": "failed",
        "error": "cURL error 56: OpenSSL SSL_read: ... decryption failed or bad record mac ..."
      }
    ],
    "first_page_url": "https://app.marketingblocks.ai/api/v1/social-sparks/get-posts?page=1",
    "from": 1,
    "last_page": 16,
    "last_page_url": "https://app.marketingblocks.ai/api/v1/social-sparks/get-posts?page=16",
    "next_page_url": "https://app.marketingblocks.ai/api/v1/social-sparks/get-posts?page=2",
    "path": "https://app.marketingblocks.ai/api/v1/social-sparks/get-posts",
    "per_page": 5,
    "prev_page_url": null,
    "to": 5,
    "total": 77
  },
  "status": true
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.marketingblocks.ai/agentic-ai-docs/api-reference/social-growth-engine/post-publishing-and-schedule/get-posts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.