Batch Posts

Batch post generation allows you to create multiple blog posts at once and schedule them to publish over time. This is perfect for content campaigns, maintaining consistent publishing schedules, or building up a content library. On this page, we'll explore how to create batches, monitor their progress, and manage scheduled posts.

Create a batch

curl -X POST https://api.waldium.com/api/v1/posts/batch-generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": {
      "strategy": "distribute",
      "startTime": "2025-01-20T14:00:00Z",
      "endTime": "2025-01-20T19:00:00Z"
    },
    "defaults": {
      "category": "Technology",
      "tags": ["AI", "Tutorial"],
      "tone": "professional"
    },
    "posts": [
      { "topic": "Introduction to Machine Learning" },
      { "topic": "Understanding Neural Networks" },
      { "topic": "Natural Language Processing Basics" },
      { "topic": "Computer Vision Applications" },
      { "topic": "AI Ethics and Best Practices" }
    ]
  }'

{
  "message": "Batch created successfully",
  "batch": {
    "id": "batch_abc123",
    "status": "pending",
    "totalPosts": 5,
    "scheduleStrategy": "distribute",
    "startTime": "2025-01-20T14:00:00Z",
    "endTime": "2025-01-20T19:00:00Z"
  },
  "scheduledPosts": [
    {
      "id": "sched_1",
      "topic": "Introduction to Machine Learning",
      "scheduledFor": "2025-01-20T14:00:00Z",
      "status": "pending"
    },
    {
      "id": "sched_2",
      "topic": "Understanding Neural Networks",
      "scheduledFor": "2025-01-20T15:00:00Z",
      "status": "pending"
    },
    {
      "id": "sched_3",
      "topic": "Natural Language Processing Basics",
      "scheduledFor": "2025-01-20T16:00:00Z",
      "status": "pending"
    },
    {
      "id": "sched_4",
      "topic": "Computer Vision Applications",
      "scheduledFor": "2025-01-20T17:00:00Z",
      "status": "pending"
    },
    {
      "id": "sched_5",
      "topic": "AI Ethics and Best Practices",
      "scheduledFor": "2025-01-20T18:00:00Z",
      "status": "pending"
    }
  ],
  "site": {
    "id": "site_123",
    "name": "Your Site Name"
  }
}

Scheduling strategies

Understanding the two scheduling strategies helps you choose the right approach for your content campaign.

Distribute strategy

The distribute strategy spreads posts evenly across a time window. This is ideal for maintaining consistent content flow throughout a period.

{
  "schedule": {
    "strategy": "distribute",
    "startTime": "2025-01-20T09:00:00Z",
    "endTime": "2025-01-20T14:00:00Z"
  }
}
// Posts at: 9:00, 9:33, 10:06, 10:40, 11:13, 11:46, 12:20, 12:53, 13:26, 14:00

Burst strategy

The burst strategy publishes posts at a fixed rate from the start time. This is perfect for content drops or rapid publishing.

{
  "schedule": {
    "strategy": "burst",
    "startTime": "2025-01-20T09:00:00Z",
    "postsPerHour": 10
  }
}
// Posts every 6 minutes starting at 9:00

Check batch status

curl -X GET https://api.waldium.com/api/v1/batches/batch_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "id": "batch_abc123",
  "status": "processing",
  "progress": {
    "total": 20,
    "pending": 8,
    "generating": 2,
    "generated": 4,
    "publishing": 1,
    "published": 5,
    "failed": 0
  },
  "nextPublishTime": "2025-01-20T15:30:00Z",
  "createdAt": "2025-01-20T09:00:00Z",
  "updatedAt": "2025-01-20T14:25:00Z"
}

Cancel a batch

curl -X DELETE https://api.waldium.com/api/v1/batches/batch_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "message": "Batch cancelled successfully",
  "cancelledPosts": 15
}

Processing timeline

Understanding how batch processing works helps you plan your content campaigns effectively.

Example timeline

For a batch created at 9:00 AM with 20 posts distributed over 4 hours:

1. 9:00 AM - Batch created, first cron run

   • Generates posts scheduled for 9:00-11:00 AM
   • Publishes any due immediately

2. 10:00 AM - Second cron run

   • Generates posts scheduled for 11:00-12:00 PM
   • Publishes posts due by 10:00 AM

3. 11:00 AM - Third cron run

   • Generates posts scheduled for 12:00-1:00 PM
   • Publishes posts due by 11:00 AM

4. 12:00 PM - Fourth cron run

   • All posts already generated
   • Publishes remaining posts

Best practices

• Schedule on the hour for most predictable publishing times
• Use 2+ hour lead time to ensure smooth generation
• Monitor batch status to track progress
• Set reasonable rates to avoid overwhelming your audience
• Use defaults to maintain consistency across posts