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.

List Jobs

Retrieve the execution history for a single schedule. scheduleId is required, and the response is paginated.

const page = await cronhost.getJobs({
  scheduleId: "schedule-123",
  status: "SUCCESS", // optional
  page: 1, // optional, 1-based
  pageSize: 50, // optional, max 100
});

console.log(page.jobs); // Job[]
console.log(page.total, page.totalPages);

Parameters:

params (GetJobsParams, required): Filter and pagination options

GetJobsParams fields:

scheduleId (string, required): The schedule whose jobs to list
status (“PENDING” | “RUNNING” | “SUCCESS” | “FAILED”, optional): Filter by job status
page (number, optional): Page number, 1-based (default: 1)
pageSize (number, optional): Jobs per page (default: 20, max: 100)

Returns: Promise<JobsPage> where JobsPage is { jobs: Job[]; page: number; pageSize: number; totalPages: number; total: number }

In SDK 1.x, getJobs() returned Job[] and scheduleId was optional. As of 2.0, scheduleId is required and the method returns a paginated JobsPage. Read the rows from page.jobs.

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 (response status below 400 by default, or one of the schedule’s expectedStatusCodes)
FAILED: Job failed due to an unexpected status code, timeout, or network issue

For the full rules on success, retries, and how executions count toward your plan, see the Execution Model.

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 jobId = await cronhost.triggerSchedule('schedule-id');
    console.log('Created job:', jobId);

    // Poll job status until completion
    let currentJob = await cronhost.getJob(jobId);
    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(jobId);
    }

    // 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 { jobs } = await cronhost.getJobs({
    scheduleId,
    status: "FAILED",
    pageSize: 20,
  });

  console.log(`Found ${jobs.length} failed jobs for schedule ${scheduleId}`);

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

// Page through all jobs for a schedule
async function getAllJobsForSchedule(scheduleId: string) {
  const allJobs: Job[] = [];
  let page = 1;

  while (true) {
    const result = await cronhost.getJobs({
      scheduleId,
      page,
      pageSize: 100,
    });

    allJobs.push(...result.jobs);

    if (page >= result.totalPages) break;
    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
  }
}

Getting Started

Core Features

Reference

Job Management

Job Management

List Jobs

Get Job by ID

Job Status Types

Example: Monitoring Job Execution

Job Object Structure

Error Handling

​Job Management

​List Jobs

​Get Job by ID

​Job Status Types

​Example: Monitoring Job Execution

​Job Object Structure

​Error Handling

Job Management

List Jobs

Get Job by ID

Job Status Types

Example: Monitoring Job Execution

Job Object Structure

Error Handling