Documentation

Bluobird is a content calendar for X (Twitter). You write posts yourself or let AI draft them, put them on a schedule, and Bluobird publishes them automatically — using your own X API keys, which are stored encrypted and never shared.

A typical setup takes about ten minutes:

1. 1Create an account with an email and password or with Google. Every account starts on the Free plan, no card required. A short setup wizard then walks you through the next two steps — every part of it can be skipped and done later.
2. 2Open Integrations and connect your X account with its API credentials (the next section walks through it).
3. 3Optionally add your OpenAI key on the same page. Without one, AI drafts still work on a shared model with a monthly allowance.
4. 4Go to Compose to post or schedule something now — type it, or press the sparkles and let AI write three versions. Use Workflows to put posting on a recurring schedule.
5. 5Watch everything from the Queue and the Calendar — every action shows its status, timing and any error there.

Bluobird posts through the official X API using credentials from your own X developer app. You create the app once in the X Developer Portal, then paste four keys into Bluobird.

Step 1 — Create an X developer app

1. 1Go to developer.x.com and sign in with the X account you want to post from. The Free tier is enough for posting.
2. 2Create a Project, then an App inside it.
3. 3In the app's Settings, open User authentication settings and set the app permissions to Read and write. Without write permission, Bluobird cannot post.
4. 4Open the Keys and tokens tab and copy four values. They map onto the Bluobird form like this:

Step 2 — Add the account in Bluobird

1. 1In Bluobird, open Integrations and click Add X account.
2. 2Fill in the four key fields. The Label is optional — use it to tell accounts apart (for example "Brand account").
3. 3Click Verify & connect. Bluobird checks the credentials against X before saving them, and stores them encrypted.

What you should see

• On success the account appears in the list with a green Verified badge.
• If verification fails you will see Could not connect the account. — almost always a mistyped key or missing write permission. Re-copy all four values and try again.
• Re-check a connection any time with the Re-test button. If X rejects the keys later, the badge flips to Unverified.
• Removing an account unlinks its workflows and queued posts; those then fail with No X account selected for this action until you pick another account.

How many X accounts you can connect depends on your plan — 1 on Free, 2 on Basic, 20 on Pro, 50 on Ultimate. The counter on the card shows where you stand.

An OpenAI key is optional. With your own key, AI drafts are unmetered by Bluobird and billed by OpenAI at their usual rates, and on paid plans ChatGPT's own web search becomes available for drafts.

1. 1Create a key at platform.openai.com/api-keys (it starts with sk-).
2. 2In Integrations, paste it into the API Key field of the OpenAI card and click Save key.
3. 3The card shows a Saved badge from then on. Leaving the field blank later keeps the stored key; pasting a new one replaces it and re-enables any workflows that were paused because the old key ran out of credits.

Compose is for one-off posts: write something now, post it now, or schedule it for later. (For recurring content, use Workflows.) It is a single box docked at the bottom of the page — type into it, or switch it to AI mode and describe what you want.

Writing it yourself

• Type the post and press the round button (or ⌘/Ctrl + Enter). It goes to the queue and publishes on the next worker tick — usually within a minute.
• The counter shows n/280 and turns red when you are over X's limit. Links always count as 23 characters.
• With more than one X account connected, Post from picks the account. With one account its handle is shown; with none, the box tells you to connect one first.
• Attach media with + — up to 4 images or 1 video per post, picked from your Media library or uploaded on the spot.
• Schedule with the clock: pick a date and time (your local time) and the post waits in the queue until then. A chip above the text shows the time; the × clears it.
• The flask toggles Dry run: the post is simulated and nothing reaches X. It is off by default in Compose.

Letting AI draft it

Press the sparkles to switch to AI mode, describe the tweet you want (up to 2,000 characters) and send. Bluobird writes up to three versions, each with its character count. Use this drops a version into the box, where you can edit it before posting; Try again asks for a fresh set.

• A picked version shows a From AI draft chip. Exactly what you see in the box is what posts — compose picks are never held for review, whatever your AI-review setting says (that setting is for workflows).
• Drafts come from your own OpenAI key when you have one, otherwise from the shared model. The line under the box says which, and how many shared drafts you have left this month.
• One prompt costs one shared draft, however many versions it produces and whether or not you post one.

AI draft settings

The gear (visible in AI mode) tunes the drafts. The choices are remembered in your browser.

• Versions per prompt — 1, 2 or 3 (default 3). Costs the same either way.
• Creativity — Precise sticks to the brief, Balanced is the default, Bold takes more liberties.
• Tone — Neutral, Casual, Pro, Witty or Bold.
• Allow hashtags (up to two) and Allow emoji — both off by default, so drafts come out clean unless you ask.

Searching the web first

The globe (AI mode, on the toolbar or under More tools on a phone) lets the AI look things up before writing, so drafts about news, prices or events are grounded in something real.

• With your own OpenAI key on a paid plan, ChatGPT's native search is used — unmetered by Bluobird, it just uses more of your OpenAI tokens.
• Otherwise Bluobird adds Google results from the last 7 days to the prompt. Each prompt with search on uses one of your plan's monthly searches (20 on Free, 100 on Basic, 500 on Pro, 2,000 on Ultimate).
• Append a source link adds the top result's URL to the end of the draft. X counts any link as 23 characters.

Both Compose and workflow rules can pull live data into a post at the moment it publishes: a price, the weather, a headline, a number from your own backend. Open API calls (the { } icon), give each call an alias and a URL, then reference the response as ${alias.field} in your text or AI prompt.

• Up to 5 calls per post or rule. Methods GET, POST, PUT, PATCH and DELETE; up to 20 headers each, and any header can be marked Secret so its value is stored encrypted and never shown again.
• Nested fields use dots: ${weather.current.temperature_2m}. Test runs the call now and shows the status, timing and the resolved values.
• Calls time out after 10 seconds and responses are capped at 512 KB. Private and localhost addresses are refused.
• If any call fails — a non-2xx status, a timeout or a truncated response — the post fails and nothing is published; the error shows on the queue row. An API error body can never end up in a tweet.
• In AI mode the calls are resolved into the prompt when the drafts are written; in workflows, when the rule runs.

Everything Bluobird is about to do — or has done — lives in the Queue: one row per action, whether it came from Compose or a workflow. Switch between Pending, Completed, Failed and All; search across text, prompts and usernames; filter by account and type; sort by newest, oldest, soonest scheduled or type. View settings shows or hides the Type, Account and When columns.

Statuses and what you can do with them

• Edit changes the text or the schedule before an action runs. Editing a draft approves it, and editing a failed action re-queues it.
• Tick rows (or the header checkbox) to select them, then Delete the selection in one go. Clear drafts removes every draft on the account at once, after a confirmation.
• Rows that say Waiting: anti-spam pacing or X rate limit are not stuck: Bluobird spaces posts out per account and retries at the time shown (see Posting limits below).
• The list shows 10 rows per page; the footer has the page controls and the total.

Workflows that draft with AI hold every post for you by default: Review AI tweets before they run is on for new accounts. Each AI post lands in the Queue as a draft with its text already generated, so you review the actual tweet, not the prompt.

1. 1Open the Queue and read the draft.
2. 2Pick Approve from the row menu — it moves to queued (or scheduled if it has a time). Not happy with it? Edit the text — saving approves it — or Cancel it.
3. 3To let AI posts publish without a click, turn the switch off under Integrations → AI preferences.

The Calendar shows what goes out and when: your scheduled and published posts alongside the runs your workflows have coming up, by month or by week (weeks start on Monday). Today jumps back to the current date.

• Scheduled and Published are real posts, placed at their time.
• ASAP is a pending post with no date — it appears on today, at the top.
• Workflow run entries are projected from each enabled workflow's schedule — no post exists yet, and the projection ignores any randomised delay. Paused, auto-stopped or over-limit workflows are not projected.
• Tap a day to open its panel: every entry with its type, account, dry-run flag and a link to the workflow that made it, plus Open in queue. The calendar itself is read-only — reschedule from the Queue.

A workflow posts on a schedule without you: AI drafts a fresh post each run, or it works through the rows of one of your datasets. The builder is a five-step wizard; you can jump between steps with the progress bars at the top.

Start from a template

You don't have to begin with a blank wizard. On the Workflows page, Templates opens a gallery of ready-made workflows — a daily AI post, a daily news take that searches the web, a tip of the day, a weekly recap, a question for your audience, two that post from a dataset, and two help-desk workflows that answer people who @mention you. Open a card to read what it does and what to change before it goes live, then choose Use this template.

• The builder opens with the name, schedule, source, AI prompt and switches already filled in, and a note at the top repeats the Before you go live list. Nothing is saved until you launch, so trying a template doesn't count towards your plan's workflows.
• Prompts mark what is yours to fill in with [square brackets] — your topic, your audience, your product. The note lists the ones still left until you have replaced them all.
• Templates start in your browser's timezone and always with Dry-run on. If a template uses Search the web and your account can't use it right now, the builder leaves it off and says why.
• Dataset templates can't know your dataset: choose it on the source step and insert your own columns into the prompt with the Insert row value chips.

1. Name your workflow

A name, the X account it posts from, and whether it is enabled as soon as it is saved. Workflows per account are capped by plan (5 on Free, 10 on Basic, unlimited on Pro, unlimited on Ultimate).

2. When should it run?

• Times are in the workflow's Timezone (UTC by default).
• Randomize posting time adds a random delay of up to the minutes you choose (60 when switched on, 1–1440) after each run time, so posts don't land at the same second every day.
• Max actions / run (1–50, default 5) caps how many posts one run may create.

3. What should it work with?

• Generate only — AI drafts a fresh post each run from your prompt. No source needed.
• Dataset — each run takes rows from one of your datasets and makes one post per row. Choose Linear (oldest first) or Randomly, add row filters such as posted equals false, and optionally limit the rows per run. The smaller of that limit and Max actions / run wins.

4. What should it do?

• Content: Manual text (up to 280 characters) or AI generated from a prompt (up to 2,000). Max length defaults to 280; longer posts need X Premium on the posting account.
• Tokens: dataset workflows can use ${record.field} (the row's values — the Insert row value chips type them for you); any workflow can use ${alias.field} from API calls.
• From templates draws the text or prompt from a random matching row of another dataset (${template.field} tokens), so one workflow can rotate through many hand-written variants. Rows with an empty template field are skipped; if none qualify the run fails with "No usable template rows".
• Search the web and Source link(s) work exactly as in Compose; each run of the rule uses one search.
• Skip duplicates steers the AI away from topics in your recent posts (the last 30 days). If the result is still a repeat after one retry, the action is cancelled with the reason on the queue row.
• Media: attach from the library (all of them, or a random one each time) or, for dataset workflows, from up to 4 image fields of the row. A video is always attached alone.
• Mark rows after posting (dataset workflows, under Advanced) sets a field after a real, non-dry-run success — for example posted = yes. With Start over when every row has been used, marked rows are skipped and, once all rows are marked, the marks are cleared and the cycle restarts; otherwise the workflow simply finds nothing to post once every row is used.

5. Fine-tune & launch

• Auto-stop after failures disables the workflow after that many failed runs in a row (default 5; 0 never stops). You get a dialog the next time you open the app, and the Workflows card shows why.
• De-dupe (on by default) never acts twice on the same dataset row within a workflow.
• Dry-run is on for every new workflow: runs are simulated, posts are logged, nothing reaches X and no operations are used. Switch it off when you have checked a run or two.

Running and managing workflows

• Each card shows Active/Paused, Dry-run/Live, the per-run cap, the schedule in plain words, next and last run, and the timezone. The switch turns it on or off; turning it on also clears any auto-stop or pause.
• Run now fires it on the next worker tick. Duplicate makes a paused copy with no account selected — edit it to pick one. Delete removes the workflow and its run history after you confirm; posts it already queued stay in the queue.
• AI workflows create draft posts while review mode is on (see Approving AI drafts). When your monthly operations run out, live workflows pause and resume automatically when the window resets or you upgrade.

Every workflow has a Logs page (from the card menu) with two tabs. Actions lists the last 50 posts it queued, published or failed, with the error when there is one; Runs lists the last 50 times the schedule fired, how many candidates were scanned and how many posts were created.

• A run's Details shows what happened to each candidate — "post queued", "skipped — max actions/run reached", "already acted on (de-duped)" and so on — so you can see exactly why a run produced what it did.
• An action's details show the final text and, once published, View posted tweet and Delete posted tweet, which removes it from X and keeps the history row.
• Common run errors: Monthly operation limit reached (upgrade or wait for the reset) and No usable template rows (the template filter matched nothing with text).

The support desk is a workflow that replies to people who @mention your account — an inbound helpdesk for the folks who reach out to you. It only ever reads your own mentions and only replies to them; it never sends anything to people who did not tag you first.

Setting one up

1. 1Go to Workflows → New workflow, name it, and under Post from choose the connected X account whose mentions you want to answer.
2. 2On the source step, pick Support desk (mentions). There is nothing else to configure — it uses the account you just chose. The only action a support-desk workflow can take is a reply.
3. 3On Compose your reply, write the reply yourself or give an AI prompt (see the tip below on referencing the mention).
4. 4Set your Schedule (how often it checks for new mentions) and Max actions / run (how many replies one run may send), then launch. Keep Dry-run on for the first run to preview replies before anything posts.

Make the AI actually answer each mention

By default an AI prompt only sees the text you write in it — not the mention it is replying to. To answer what each person actually said, reference the mention with these tokens in your prompt (or in manual text):

For example: A user (@${tweet.author}) replied "${tweet.text}" to our tweet "${tweet.parentText}". Write a warm, helpful reply that answers them in that context and offers further help.

How it behaves

• Each run pulls your most recent mentions and replies only to the new ones — it never replies to the same mention twice.
• It sends at most Max actions / run replies per run, so a burst of mentions can't fan out uncontrollably.
• The first run picks up mentions already sitting in your timeline (not just ones that arrive after you turn it on) — another reason to dry-run it first.
• If you keep AI review on, each reply waits in the Queue as a draft for your approval before it sends; turn review off for fully automatic replies.

Datasets let workflows post from your own structured content — a CSV of tips, products, quotes, or anything else with one row per post. The file is parsed in your browser; only the rows are stored.

Importing a CSV

1. 1On Datasets, click New dataset and pick a CSV file. The first row must be a header row — column names become fields.
2. 2Choose which columns to import and rename their labels if you like. Field keys are derived from the labels (lowercase, underscores) — workflows reference rows by key.
3. 3Name the dataset and import. Into an existing dataset you can Append rows or Overwrite everything.

Working with a dataset

• Add field adds a text field (optionally with a default value for every existing row) or an image field. Image fields hold one image or video per row, picked from the Media library or uploaded into the cell; up to 4 per dataset, attached to posts in column order.
• Click any text cell to edit it in place; Enter saves, Escape cancels. The arrows in a column header reorder fields, the bin deletes one (a dataset keeps at least one field).
• Rows are added or replaced by CSV import; 100 rows load at a time with a Load more button.

Limits

Common import messages: No columns found. Is this a CSV with a header row? means the file is missing its header line, and That file has headers but no data rows. means only the header was found — check the export from your spreadsheet tool. An import that would exceed your plan's rows tells you the exact limit.

The Media page holds the images and videos your posts attach. Upload with the button or by dragging files in; open a tile to preview, download or delete it.

• Images (JPG, PNG, and other common formats): up to 2 MB each. Videos (MP4 or MOV): up to 50 MB.
• A post can carry up to 4 images or 1 video — never both. The attach picker in Compose and in workflows enforces this.
• In a workflow you can attach everything you picked or Random one per post.
• Deleting a file removes it from the library; queued posts and workflows that referenced it simply post without it.

Files that break a rule are rejected individually with a specific message — for example photo.jpg is 3.4MB — images must be under 2MB. The rest of the batch still uploads.

Bluobird is usage-based: one operation = one executed, real action. Dry runs, drafts and cancelled posts are free. Your monthly window is anchored to the day you signed up (or last upgraded) and resets on that day each month.

• Payments are handled by Paddle, our Merchant of Record. Manage subscription opens the Paddle portal to update your card, download invoices or cancel.
• Upgrading charges the new plan's full price today and restarts your usage month: operations and AI-draft counters start from zero and the renewal moves to a month from now. Limits are replaced, not added up.
• Downgrading keeps what you have used and the current reset date; the dialog warns you if your workflows, datasets or accounts are already over the new plan's limits. Switch to Free takes effect at the end of the paid period.
• At 80% of your operations you get a banner and an email; at 100% live workflows pause and further real posts fail with Monthly operation limit reached until the window resets or you upgrade — then everything resumes on its own. Posts are held, not lost.
• A failed renewal gives you 7 days to update the card; after that the account moves to Free.

Settings has four tabs. Profile holds your picture and name. Account changes your email (you confirm the new address by link) and has the Product updates by email switch: turn it off to stop occasional emails about new features — emails about your own account, like password resets and alerts, are always sent. Security changes your password and sets up multi-factor authentication with an authenticator app. Advanced is where your data is yours.

• Download my data (JSON) gives you your profile, X handles, workflows, posts, datasets, media list and usage (up to 10,000 rows per table). Encrypted credentials are never included.
• Delete your account — type DELETE to confirm. The subscription is cancelled immediately with no refund, and every row of your data is erased. It cannot be undone.
• Sign in with your email and password or with Google; reset your password by email if you forget it. With MFA enabled, every sign-in asks for a code.

Bluobird paces every account the way a careful human would, so your X account stays in good standing. These limits apply per connected X account to real (non-dry-run) posts; you never have to configure them.

• Paced or rate-limited posts are rescheduled, never dropped.
• Each post or workflow belongs to exactly one X account; there is no "post to all accounts". Posting the same content from several accounts is against X's rules and our Acceptable Use Policy.
• Dry runs bypass all of this — they never reach X.

Banners you may see

• Running low / out of operations — at 80% and 100% of your monthly operations, with an Upgrade button. Out means live workflows are paused until the reset.
• OpenAI key out of credits — your own key stopped working, so AI workflows were paused. Top up at OpenAI, then re-enable them (saving a new key does this for you).
• Over your workflow limit — after a downgrade you have more workflows than the plan allows. Delete some or upgrade.
• A workflow auto-stopped — it failed several runs in a row (see Auto-stop). Fix the cause, then switch it back on.
• Your account has been paused — nothing posts and nothing saves while a review is in progress; contact support.

The most common issues, what they mean, and how to fix them. For anything else, contact us — include the exact error text from the queue row if there is one.