Optimized posts

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:

Research: the business (its website and what you send), its competitors on that network, and the headlines and trends its audience is talking about.
Ideas: five post ideas built on the research, and it picks the strongest.
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.
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, 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

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:

{
  "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)

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

{
  "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 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.

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)
`404`	No optimized post with that id in this workspace

Getting Started

Concepts

Quick Agent Actions

Lincoln AI

Videos

Predictions

Video Schedules

Calls, Texts and Contacts

Account

Sub-entities

Billing

Phone Numbers

Number Configuration

Caller IDs

Enterprise Registration

Enterprise Registration (Legacy)

Branded Calling

Dialer Calls

Call Webhooks

Inbound SMS

SMS

WebRTC

Documents

Reputation

Usage

Optimized posts

Pricing

Written for

Start a post

Wait for it

Post it

Errors

​Pricing

​Written for

​Start a post

​Wait for it

​Post it

​Errors

Pricing

Written for

Start a post

Wait for it

Post it

Errors