# Upcoming Posts

Endpoint:\
`GET https://app.marketingblocks.ai/api/v1/social-sparks/upcoming-posts`

This endpoint retrieves upcoming scheduled, queued, or next-share social posts. Results are ordered by schedule time closest to the current time.\
Requires the `social-read-posts` permission.

### Authentication

Type: Bearer Token

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

### Request Parameters

| Parameter |    Type | Required | Default | Description                                                   |
| --------- | ------: | :------: | ------: | ------------------------------------------------------------- |
| `limit`   | integer |    No    |    `10` | Number of upcoming posts to return. Must be greater than `0`. |

### Example Request

#### cURL

```bash
curl --location --request GET \
'https://app.marketingblocks.ai/api/v1/social-sparks/upcoming-posts?limit=10' \
--header 'Authorization: Bearer <token>'
```

#### Plain URL

```http
GET https://app.marketingblocks.ai/api/v1/social-sparks/upcoming-posts?limit=10
```

### Response Structure

The response is a JSON object with one main key:

| Key         | Type  | Description                    |
| ----------- | ----- | ------------------------------ |
| `up_coming` | array | List of upcoming social posts. |

### Upcoming Post Object

| Field           | Type    | Description                                                                     |
| --------------- | ------- | ------------------------------------------------------------------------------- |
| `post_id`       | integer | Unique ID of the social post.                                                   |
| `channel_type`  | string  | Social platform type, for example `instagram`, `threads`, `facebook`, `tiktok`. |
| `channel_id`    | string  | Connected social channel/account ID.                                            |
| `STATUS`        | string  | Current publish status, for example `queued` or `scheduled`.                    |
| `schedule_time` | string  | Scheduled publish time, formatted using the post timezone.                      |
| `time_zone`     | string  | IANA timezone used for the schedule time, for example `Africa/Lagos`.           |

### Example Response

```json
{
  "up_coming": [
    {
      "post_id": 122524,
      "channel_type": "threads",
      "channel_id": "4125",
      "STATUS": "queued",
      "schedule_time": "4PM, 4th of May, 2026",
      "time_zone": "Africa/Lagos"
    },
    {
      "post_id": 114722,
      "channel_type": "instagram",
      "channel_id": "4500",
      "STATUS": "scheduled",
      "schedule_time": "2PM, 8th of August, 2026",
      "time_zone": "America/New_York"
    }
  ]
}
```

### Error Responses

#### Missing Permission

```json
{
  "message": "You do not have permission to read posts.",
  "status": false
}
```

HTTP status: `422`

#### Server Error

```json
{
  "up_coming": [],
  "message": "Error message here"
}
```

HTTP status: `500`


---

# 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/upcoming-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.