Skip to main content

​
Quick Start

Get started with cronhost and create your first scheduled HTTP request in just a few minutes.

​
1. Get Your API Key

First, you’ll need an API key to authenticate with the cronhost API.
  1. Visit the cronhost Dashboard
  2. Sign up for a free account or log in
  3. Navigate to Settings
  4. Generate a new API key and copy it
Keep your API key secure! Don’t expose it in client-side code or public repositories.

​
2. Create Your First Schedule

​
Using cURL

Here’s how to create a simple schedule that checks an API every hour: 
curl -X POST "https://cronho.st/api/v1/schedules" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hourly Health Check",
    "description": "Check if our API is healthy every hour",
    "cronExpression": "0 * * * *",
    "timezone": "UTC",
    "endpoint": "https://api.example.com/health",
    "httpMethod": "GET",
    "maxRetries": 3,
    "timeoutSeconds": 30
  }'

​
Using the TypeScript SDK

For a better developer experience, use our official TypeScript SDK: 
npm install cronhost

import { Cronhost } from "cronhost";

const cronhost = new Cronhost({
  apiKey: "YOUR_API_KEY",
});

const schedule = await cronhost.createSchedule({
  name: "Hourly Health Check",
  description: "Check if our API is healthy every hour",
  cronExpression: "0 * * * *",
  timezone: "UTC",
  endpoint: "https://api.example.com/health",
  httpMethod: "GET",
  maxRetries: 3,
  timeoutSeconds: 30,
});

console.log("Schedule created:", schedule.id);

​
3. Understanding Cron Expressions

cronhost uses standard 5-field cron expressions: 
┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of week (0 - 7) (Sunday=0 or 7)
│ │ │ │ │
* * * * *

​
Common Examples

ExpressionDescription
0 9 * * *Every day at 9 AM
*/15 * * * *Every 15 minutes
0 0 * * 0Every Sunday at midnight
0 12 1 * *First day of every month at noon
30 14 * * 1-5Weekdays at 2:30 PM

​
3. Choosing the Right Timezone

All schedules require a timezone to ensure your HTTP requests run at the correct local time. Use IANA timezone identifiers for accuracy: 
// Examples of timezone usage
const schedule = await cronhost.createSchedule({
  name: "East Coast Business Hours",
  cronExpression: "0 9 * * 1-5", // Weekdays at 9 AM
  timezone: "America/New_York", // Handles EST/EDT automatically
  endpoint: "https://api.example.com/check",
});
Need help choosing a timezone? Check out our Timezone Reference for a complete list of supported IANA identifiers and regional examples.

​
4. Monitor Your Schedule

​
Check Schedule Status

curl -H "x-api-key: YOUR_API_KEY" \
  "https://cronho.st/api/v1/schedules/SCHEDULE_ID"

​
View Job History

curl -H "x-api-key: YOUR_API_KEY" \
  "https://cronho.st/api/v1/jobs?scheduleId=SCHEDULE_ID&limit=10"

​
Using the SDK

// Get schedule details
const schedule = await cronhost.getSchedule("SCHEDULE_ID");
console.log("Next run:", schedule.nextRunAtUtc);

// Get recent jobs
const jobs = await cronhost.getJobs({
  scheduleId: "SCHEDULE_ID",
  limit: 10,
});

jobs.forEach((job) => {
  console.log(`Job ${job.id}: ${job.status} - ${job.completedAtUtc}`);
});

​
5. Common Use Cases

​
API Health Monitoring

Monitor your API endpoints and get notified of downtime: 
const healthCheck = await cronhost.createSchedule({
  name: "API Health Monitor",
  cronExpression: "*/5 * * * *", // Every 5 minutes
  timezone: "UTC",
  endpoint: "https://your-api.com/health",
  httpMethod: "GET",
  maxRetries: 2,
  timeoutSeconds: 10,
});

​
Webhook Triggers

Send scheduled webhooks to external services: 
const weeklyReport = await cronhost.createSchedule({
  name: "Weekly Report Webhook",
  cronExpression: "0 9 * * 1", // Every Monday at 9 AM
  timezone: "America/New_York",
  endpoint: "https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK",
  httpMethod: "POST",
  body: JSON.stringify({
    text: "Weekly report is ready for review!",
  }),
  headers: {
    "Content-Type": "application/json",
  },
});

​
Data Processing

Schedule batch jobs for data processing: 
const dailyBackup = await cronhost.createSchedule({
  name: "Daily Database Backup",
  cronExpression: "0 2 * * *", // Every day at 2 AM
  timezone: "UTC",
  endpoint: "https://your-api.com/backup/trigger",
  httpMethod: "POST",
  headers: {
    Authorization: "Bearer YOUR_TOKEN",
  },
  maxRetries: 1,
  timeoutSeconds: 300, // 5 minutes for longer operations
});

​
6. Managing Schedules

​
Update a Schedule

const updated = await cronhost.updateSchedule("SCHEDULE_ID", {
  cronExpression: "0 */2 * * *", // Change to every 2 hours
  maxRetries: 5,
});

​
Temporarily Disable

// Disable schedule
await cronhost.toggleSchedule("SCHEDULE_ID", false);

// Re-enable later
await cronhost.toggleSchedule("SCHEDULE_ID", true);

​
Manual Trigger

// Trigger immediately for testing
const job = await cronhost.triggerSchedule("SCHEDULE_ID");
console.log("Triggered job:", job.id);

​
7. Error Handling

Always handle errors gracefully: 
try {
  const schedule = await cronhost.createSchedule({
    // ... schedule data
  });
  console.log("Success!", schedule.id);
} catch (error) {
  console.error("Failed to create schedule:", error.message);

  // Check for specific error types
  if (error.message.includes("Invalid cron expression")) {
    console.log("Please check your cron syntax");
  }
}

​
Next Steps

Explore the API

Dive deeper into all available endpoints

SDK Documentation

Learn about advanced SDK features

Job Monitoring

Monitor execution history and debug issues

Best Practices

Learn tips for production usage

​
Need Help?

You’re now ready to start scheduling HTTP requests with cronhost! 🚀