Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cronho.st/llms.txt

Use this file to discover all available pages before exploring further.

​
Job Management

Jobs represent individual executions of your scheduled HTTP requests. Each time a schedule runs (either automatically via cron or manually triggered), it creates a job that tracks the execution details, status, and results.

​
Get All Jobs

Retrieve jobs with optional filtering parameters. 
// Get all jobs
const allJobs = await cronhost.getJobs();

// Get jobs with filters
const filteredJobs = await cronhost.getJobs({
  scheduleId: 'schedule-123',
  status: 'SUCCESS',
  page: 1,
  limit: 50
});
Parameters:
  • params (GetJobsParams, optional): Object containing filter options
GetJobsParams fields (all optional):
  • scheduleId (string): Filter jobs by specific schedule ID
  • status (“PENDING” | “RUNNING” | “SUCCESS” | “FAILED”): Filter by job status
  • page (number): Page number for pagination (default: 1)
  • limit (number): Number of jobs per page (default: 10, max: 100)
Returns: Promise<Job[]>

​
Get Job by ID

Retrieve detailed information about a specific job. 
const job = await cronhost.getJob('job-id');
Parameters:
  • id (string, required): The unique identifier of the job
Returns: Promise<Job>

​
Job Status Types

Jobs can have one of four statuses:
  • PENDING: Job is queued and waiting to execute
  • RUNNING: Job is currently executing the HTTP request
  • SUCCESS: Job completed successfully (HTTP status 2xx)
  • FAILED: Job failed due to HTTP error, timeout, or network issue

​
Example: Monitoring Job Execution

import { Cronhost } from 'cronhost';

const cronhost = new Cronhost({
  apiKey: 'your-api-key'
});

async function monitorJobs() {
  try {
    // Trigger a schedule to create a new job
    const job = await cronhost.triggerSchedule('schedule-id');
    console.log('Created job:', job.id);

    // Poll job status until completion
    let currentJob = job;
    while (currentJob.status === 'PENDING' || currentJob.status === 'RUNNING') {
      console.log(`Job ${currentJob.id} status: ${currentJob.status}`);
      
      // Wait 2 seconds before checking again
      await new Promise(resolve => setTimeout(resolve, 2000));
      
      // Fetch updated job status
      currentJob = await cronhost.getJob(job.id);
    }

    // Job completed
    console.log('Final job status:', currentJob.status);
    
    if (currentJob.status === 'SUCCESS') {
      console.log('Response status code:', currentJob.statusCode);
      console.log('Response body:', currentJob.response);
    } else if (currentJob.status === 'FAILED') {
      console.log('Error message:', currentJob.errorMessage);
    }

  } catch (error) {
    console.error('Monitoring error:', error.message);
  }
}

// Get recent failed jobs for a specific schedule
async function getFailedJobs(scheduleId: string) {
  const failedJobs = await cronhost.getJobs({
    scheduleId,
    status: 'FAILED',
    limit: 20
  });

  console.log(`Found ${failedJobs.length} failed jobs for schedule ${scheduleId}`);
  
  failedJobs.forEach(job => {
    console.log(`Job ${job.id}: ${job.errorMessage}`);
  });
}

// Get jobs across all schedules with pagination
async function getAllJobsPaginated() {
  let page = 1;
  let allJobs: Job[] = [];
  
  while (true) {
    const jobs = await cronhost.getJobs({
      page,
      limit: 100
    });
    
    if (jobs.length === 0) break;
    
    allJobs.push(...jobs);
    page++;
  }
  
  console.log(`Retrieved ${allJobs.length} total jobs`);
  return allJobs;
}

monitorJobs();

​
Job Object Structure

Each job contains detailed execution information: 
interface Job {
  id: string;                    // Unique job identifier
  scheduleId: string;           // Associated schedule ID
  status: "PENDING" | "RUNNING" | "SUCCESS" | "FAILED";
  scheduledRunAtUtc: Date;      // When the job was supposed to run
  attemptNumber: number;        // Current retry attempt (1-based)
  httpMethod: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
  endpoint: string;             // Target endpoint URL
  body?: string;                // Request body (if applicable)
  headers?: string;             // Request headers as JSON string
  statusCode?: number;          // HTTP response status code
  response?: string;            // HTTP response body
  startedAtUtc?: Date;         // When execution started
  completedAtUtc?: Date;       // When execution completed
  errorMessage?: string;        // Error details (if failed)
  createdAt: Date;             // Job creation timestamp
  updatedAt: Date;             // Last update timestamp
}

​
Error Handling

When monitoring jobs, handle potential errors: 
async function safeGetJob(jobId: string) {
  try {
    const job = await cronhost.getJob(jobId);
    return job;
  } catch (error) {
    if (error.message.includes('not found')) {
      console.log('Job not found');
      return null;
    }
    throw error; // Re-throw other errors
  }
}