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:

npm install cronhost

yarn add cronhost

pnpm add cronhost

bun add 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

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&pageSize=10"

Using the SDK

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

// Get recent jobs (paginated; scheduleId is required)
const { jobs } = await cronhost.getJobs({
  scheduleId: "SCHEDULE_ID",
  pageSize: 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 jobId = await cronhost.triggerSchedule("SCHEDULE_ID");
console.log("Triggered job:", jobId);

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?

API Issues: Check our API documentation
SDK Questions: See the SDK reference
Support: Email us at help@cronho.st
Status: Check status.cronho.st for service status

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

Get Started

Reference

Quickstart Guide

Quick Start

1. Get Your API Key

2. Create Your First Schedule

Using cURL

Using the TypeScript SDK

3. Understanding Cron Expressions

Common Examples

3. Choosing the Right Timezone

4. Monitor Your Schedule

Check Schedule Status

View Job History

Using the SDK

5. Common Use Cases

API Health Monitoring

Webhook Triggers

Data Processing

6. Managing Schedules

Update a Schedule

Temporarily Disable

Manual Trigger

7. Error Handling

Next Steps

Explore the API

SDK Documentation

Job Monitoring

Best Practices

Need Help?

​Quick Start

​1. Get Your API Key

​2. Create Your First Schedule

​Using cURL

​Using the TypeScript SDK

​3. Understanding Cron Expressions

​Common Examples

​3. Choosing the Right Timezone

​4. Monitor Your Schedule

​Check Schedule Status

​View Job History

​Using the SDK

​5. Common Use Cases

​API Health Monitoring

​Webhook Triggers

​Data Processing

​6. Managing Schedules

​Update a Schedule

​Temporarily Disable

​Manual Trigger

​7. Error Handling

​Next Steps

Explore the API

SDK Documentation

Job Monitoring

Best Practices

​Need Help?

Quick Start

1. Get Your API Key

2. Create Your First Schedule

Using cURL

Using the TypeScript SDK

3. Understanding Cron Expressions

Common Examples

3. Choosing the Right Timezone

4. Monitor Your Schedule

Check Schedule Status

View Job History

Using the SDK

5. Common Use Cases

API Health Monitoring

Webhook Triggers

Data Processing

6. Managing Schedules

Update a Schedule

Temporarily Disable

Manual Trigger

7. Error Handling

Next Steps

Need Help?