Scheduled Headlines API | SEObot Help Center

List the headlines queued for article generation on your SEObot website, in the exact order they'll be generated. Use it to see what's coming next and to decide when to top up the queue (via the Add Headlines API).

Endpoint

GET https://app.seobotai.com/api/v1/headlines/scheduled?key=YOUR_API_KEY

Authentication

Pass your website API key as the key query parameter (same key as the Add Headlines API). The key identifies the target website — you don't pass host.

Query parameters

Param	Type	Required	Description
`key`	string	yes	Per-website API key.
`page`	number	no	Zero-based page, default `0`.
`limit`	number	no	Items per page, default `100`, max `500`.

Response

{
   "success": true,
   "summary": {
     "total": 42,
     "queued": 41,
     "generating": 1,
     "pendingApproval": 0,
     "remainingCredits": 120,
     "perPeriod": 7,
     "period": "week"
   },
   "page": 0,
   "limit": 100,
   "scheduled": [
     {
       "position": 1,
       "id": "65f1c2a4e7b9d1a3f4e2c5b8",
       "headline": "Best CRMs for Small Business in 2026",
       "slug": "best-crms-for-small-business-2026",
       "state": "generating",
       "prioritized": false,
       "hasContext": true,
       "createdAt": "2026-05-19T09:00:00.000Z"
     },
     {
       "position": 2,
       "id": "65f1c2a4e7b9d1a3f4e2c5b9",
       "headline": "How to Run a Lead Scoring Campaign",
       "slug": "how-to-run-a-lead-scoring-campaign",
       "state": "queued",
       "prioritized": false,
       "hasContext": false,
       "createdAt": "2026-05-19T09:01:00.000Z"
     }
   ]
}

The scheduled array is ordered the same way the generator picks work: whatever is currently generating comes first, then queued headlines in the order they'll be picked up. scheduled[0] is effectively "what's being worked on / next up".

`summary`

Field	Type	Description
`total`	number	Headlines in the generation queue (`queued` + `generating`). The size of the full list across all pages.
`queued`	number	Headlines waiting to start.
`generating`	number	Headlines currently being turned into articles (usually 0 or 1).
`pendingApproval`	number	AI-suggested headlines awaiting your approval. Not in the `scheduled` list — they only enter the queue once approved.
`remainingCredits`	number	Article credits left on your plan (how many more articles can be generated in total).
`perPeriod`	number \| null	How many articles your plan generates per period.
`period`	string	The pacing period: `"day"`, `"week"`, or `"month"`.

Rough runway estimate: queued / perPeriod periods of content remaining. When that gets low (and remainingCredits is healthy), top up with more headlines.

`scheduled[]`

Field	Type	Description
`position`	number	1-based position in the overall queue (continues across pages).
`id`	string	Unique identifier of the headline.
`headline`	string	The headline text.
`slug`	string	Current URL slug.
`state`	`"generating"` \| `"queued"`	`generating` = article is being built now; `queued` = waiting its turn.
`prioritized`	boolean	`true` if this headline was flagged to jump ahead of the normal FIFO order.
`hasContext`	boolean	Whether custom context is attached to this headline.
`createdAt`	string	ISO timestamp of when the headline was added.

Errors

Same shape as the Add Headlines API:

{ "success": false, "code": "INVALID_KEY", "error": "Wrong API key" }

`code`	Meaning
`MISSING_KEY`	`key` query param missing or empty.
`INVALID_KEY`	`key` doesn't match any website.
`WEBSITE_NOT_FOUND`	Key resolved a host but the website record is missing (rare; stale key).

Example

curl "https://app.seobotai.com/api/v1/headlines/scheduled?key=YOUR_API_KEY&limit=20"

const res = await fetch(
  `https://app.seobotai.com/api/v1/headlines/scheduled?key=${KEY}`,
).then(r => r.json());

const { queued, perPeriod, period, remainingCredits } = res.summary;

console.log(`${queued} queued (~${(queued / perPeriod).toFixed(1)} ${period}s of runway), ${remainingCredits} credits left`);

console.log('Next up:', res.scheduled[0]?.headline ?? '(queue empty)');

if (queued < perPeriod && remainingCredits > 0) {
   // queue is running low — top up via POST /api/v1/headlines
}

How do I integrate SEObot via REST API?

Add Headlines API