> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumisreach.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Optimized posts

> Make a text post, or a text post with one picture, researched and written to perform on X, LinkedIn or Instagram.

These endpoints make a social post the way the dashboard's **Create Post → Generate Automatically**
does. You send what the business is and the network the post is for; the post producer does the rest,
with no one in the loop:

1. **Research**: the business (its website and what you send), its competitors on that network, and the
   headlines and trends its audience is talking about.
2. **Ideas**: five post ideas built on the research, and it picks the strongest.
3. **Writing**: the tuned writer writes five drafts for the idea and keeps the best. It learns from the
   posts that did best and worst for accounts like yours on that network, each measured against its own
   account's usual post, and follows that network's craft.
4. **The picture**, for an `image` post: one of your own `source_image_urls`, or one drawn by AI to go
   with the words.

That is the difference from a `slideshow` made with [`POST /v1/videos`](https://docs.lumisreach.com/api-reference/videos), which is
written plainly from your sources.

| Endpoint | What it does | Scope |
| - | - | - |
| `POST /v1/optimized-posts` | Start an optimized post | `videos:write` |
| `GET /v1/optimized-posts/{id}` | Where it stands and, once ready, the post | `videos:read` |
| `POST /v1/videos/{video_id}/posts` | Post it to your connected accounts | `videos:write` |

## Pricing

What a post costs depends on the plan:

| Plan | Optimized posts |
| - | - |
| API & MCP | Charged per post: provider cost plus 20% |
| Growth Marketing Manager (agent hire) | Charged per post: provider cost plus 20%, included credits first |
| Revenue Engine, Custom | Free |
| Any other plan | Not included: `POST` returns `403 plan_not_included` |

A charged post costs what goes into it plus 20%: the writing, its picture, and for a post written for
Instagram, reading Instagram for the writer. It is charged once, when the post is made, from your included
video credits first, then your prepaid balance, and shows up as `ai_video` in
`GET /v1/billing/events`, labelled "via API". Typical prices:

| Post | Price |
| - | - |
| `text`, X or LinkedIn | 12¢ |
| `image` with an AI picture, X or LinkedIn | 18¢ |
| `image` with an AI picture, Instagram | 59¢ |

An Instagram post costs more because its writer reads Instagram live: about 130 posts and profiles of
accounts like yours (41¢ of the 59¢). That read is charged once per post, only if it succeeds. `price_cents`
on the post is that estimate until the post is made, then what it was charged. Posting is free.

## Written for

`written_for` picks the network the post is written for: `x`, `linkedin` or `instagram`. Each rewards a
different post, so the research studies competitors on that network only, and the writer follows its
craft:

| `written_for` | What the writer learns from | The post |
| - | - | - |
| `x` | About 300 posts by the 30+ accounts most like yours, from our X dataset | One punchy post under 280 characters, no question at the end |
| `linkedin` | About 300 posts by the 30+ accounts most like yours, from our LinkedIn dataset | 700 to 1,300 characters, a hook before "see more", short lines, no link |
| `instagram` | Picture posts of accounts like yours, read live from Instagram | A caption whose first line hooks before "more", a few niche hashtags |

On X and LinkedIn, the writer's five drafts are scored by our post models and the best one is kept. On
Instagram there is no post model to score them, so the first draft that passes the writer's checks is
kept. Instagram takes no text-only post: `format: text` with `written_for: instagram` is refused with
`400`. Omit `written_for` to write one post for X and LinkedIn at once.

## Start a post

```bash theme={null}
curl -X POST "https://api.lumisreach.com/api/v1/optimized-posts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "image",
    "written_for": "instagram",
    "brief": "Our new weekend sourdough, for people who order bread for the week",
    "source_url": "https://acmebakery.example"
  }'
```

| Field | What it is |
| - | - |
| `format` | `text` (the words alone) or `image` (the words with one picture). Default `image`. |
| `written_for` | `x`, `linkedin` or `instagram`. Omit for X and LinkedIn at once. |
| `brief` | What the post should be about: the subject, the audience and the feel. |
| `source_url` | The business's website. Omit to use the one saved in the workspace's marketing profile. |
| `source_text` | A description of the business, product or offer. Needed when there is no website to read. |
| `source_image_urls` | Images already uploaded to the workspace; an `image` post uses one instead of drawing one. |
| `title` | Your name for the post. Omit it and one is written. |
| `language` | The language the post is written in (`en`, `es`, `fr`, ...). Default `en`. |

It runs in the background, so this answers `201` straight away:

```json theme={null}
{
  "data": {
    "id": "0b5c4a39-8f53-4d0e-9c0f-3d0e1d1f9a11",
    "status": "researching",
    "format": "image",
    "written_for": "instagram",
    "title": null,
    "text": null,
    "image_url": null,
    "video_id": null,
    "price_cents": 59,
    "price_estimated": true,
    "billed_cents": null,
    "error": null,
    "dashboard_url": "https://app.lumisreach.com/viral-content/post?agent=0b5c4a39-8f53-4d0e-9c0f-3d0e1d1f9a11",
    "created_at": "2026-10-27T18:00:00.000Z",
    "updated_at": "2026-10-27T18:00:00.000Z"
  }
}
```

Open `dashboard_url` to watch the producer work: its research, its five ideas, and the post.

## Wait for it

Poll `GET /v1/optimized-posts/{id}` every 15 to 30 seconds. A post usually takes a few minutes, most of it
research.

| `status` | What is happening |
| - | - |
| `researching` | Reading the business, its competitors and the news |
| `writing` | Recommending ideas, picking one, writing the post |
| `producing` | Making the picture and finishing the post |
| `ready` | Done: `text`, `image_url` and `video_id` are filled in |
| `failed` | It could not be made; `error` says why. The post is not charged (a read of Instagram that already happened is) |

```bash theme={null}
curl "https://api.lumisreach.com/api/v1/optimized-posts/0b5c4a39-8f53-4d0e-9c0f-3d0e1d1f9a11" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "data": {
    "id": "0b5c4a39-8f53-4d0e-9c0f-3d0e1d1f9a11",
    "status": "ready",
    "format": "image",
    "written_for": "instagram",
    "title": "Weekend sourdough",
    "text": "Our weekend sourdough sells out by 11am, so here is how to get one every week.\n\nOrder by Thursday night and we bake yours Saturday at 5am. Pick it up warm, or we drop it at your door.\n\nSave this for your next order.\n\n#sourdough #weekendbaking #localbakery",
    "image_url": "https://app.lumisreach.com/api/viral-videos/slides/...",
    "video_id": "7d1e2f3a-4b5c-4d6e-8f9a-0b1c2d3e4f5a",
    "price_cents": 59,
    "price_estimated": false,
    "billed_cents": 59,
    "error": null,
    "dashboard_url": "https://app.lumisreach.com/viral-content/post?agent=0b5c4a39-8f53-4d0e-9c0f-3d0e1d1f9a11",
    "created_at": "2026-10-27T18:00:00.000Z",
    "updated_at": "2026-10-27T18:04:12.000Z"
  }
}
```

## Post it

The finished post is a video record (template `slideshow`), so it posts like a video: pass its `video_id`
to [`POST /v1/videos/{id}/posts`](https://docs.lumisreach.com/api-reference/videos#posting) with the accounts from
`GET /v1/social-connections`, now or at `scheduled_for`. `GET /v1/videos/{video_id}` has every detail of
it. You can also predict how it will do first with [Predictions](https://docs.lumisreach.com/api-reference/predictions.md).

## Errors

| Status | When |
| - | - |
| `400` | `format: text` for Instagram, no `source_url` or `source_text` with no saved website, or an image not uploaded to this workspace |
| `403 plan_not_included` | The plan does not include making posts through the API (see [Pricing](#pricing)) |
| `404` | No optimized post with that id in this workspace |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.