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.
- Visit the cronhost Dashboard
- Sign up for a free account or log in
- Navigate to Settings
- 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:
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
| Expression | Description |
|---|
0 9 * * * | Every day at 9 AM |
*/15 * * * * | Every 15 minutes |
0 0 * * 0 | Every Sunday at midnight |
0 12 1 * * | First day of every month at noon |
30 14 * * 1-5 | Weekdays 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
Need Help?
You’re now ready to start scheduling HTTP requests with cronhost! 🚀