Skip to main content

Job API Overview

The Informer Job API provides comprehensive endpoints for creating and managing scheduled jobs, automated workflows, and data processing tasks. Jobs support recurring schedules, dataset operations, email notifications, library updates, and custom actions with conditions and attachments. All routes are prefixed with /api.

Features​

  • CRUD Operations - Create, read, update, and delete jobs
  • Scheduling - Cron-style intervals with timezone support, start/end dates
  • Actions - Multi-step workflows with conditional execution
  • Attachments - Add reports, files, and data to action outputs
  • Run History - Track execution logs, success/failure, duration, progress
  • Dataset Associations - Reference datasets with snapshot support
  • Draft Workflow - Edit jobs safely without affecting production
  • Workers - Distributed job execution across cluster nodes
  • Drivers & Templates - Extensible job types (email, dataset refresh, API calls, etc.)

Job Types​

Jobs are created with different driver types:

TypeDescription
emailSend scheduled emails with attachments
dataset-refreshRefresh dataset from datasource query
library-syncSync library files from cloud integration
index-filesIndex library files for vector search
api-callMake HTTP requests to external APIs
snapshot-cleanupAutomatically clean up old dataset snapshots

Authentication​

All Job API endpoints require authentication via session cookies or API tokens. Most endpoints verify job permissions before allowing access.

Common Permission Patterns​

  • Read access - View job configuration and history (requires ownership or share)
  • Edit permission - Required for job:edit (update, create draft)
  • Run permission - Required for job:run (manually trigger execution)
  • Delete permission - Required for job:delete (remove job)

Scheduling​

Jobs use cron-style intervals with additional options:

  • interval - Cron expression or simple interval (e.g., "0 0 * * *" for daily at midnight, "1 hour")
  • intervalType - Interval type: cron, simple, once
  • startOn - Start date (job won't run before this)
  • endOn - End date (job won't run after this)
  • timezone - Timezone for schedule interpretation (e.g., America/New_York)
  • enabled - Boolean to enable/disable execution

Fire Times​

Preview upcoming execution times via GET /api/job-fire-times?interval=...&timezone=...

Actions & Attachments​

Jobs execute one or more actions in sequence:

  1. Job Actions - Steps in the workflow (e.g., send email, call API)
  2. Run Conditions - Rules to skip actions based on previous results
  3. Attachments - Files, reports, or data to include in action output

Action Drivers​

Common action types:

DriverDescription
emailSend email with optional attachments
webhookHTTP POST to external URL
datasetPerform dataset operations
libraryUpdate library files

Dataset Associations​

Jobs can reference datasets:

  • Alias - Short name for dataset reference in job context
  • Snapshots - Configure automatic dataset snapshots before/after job runs
  • Permissions - Check if user has access to job's datasets

Draft Workflow​

Edit jobs safely without affecting scheduled execution:

  1. Create draft - POST /api/jobs/{id}/_edit
  2. Modify draft - Changes only affect the draft version
  3. Commit draft - POST /api/jobs/{id}/_commit to publish changes

Run History​

Track job execution:

  • Success/Failure - Boolean status and error messages
  • Duration - Start and end timestamps
  • Progress - Step-by-step logs with status
  • Warnings - Non-fatal issues during execution

Workers​

Jobs are executed by distributed workers:

  • Heartbeat - Workers send periodic heartbeats to indicate liveness
  • Concurrency - Maximum concurrent jobs per tenant/cluster
  • Timeout - Jobs time out if heartbeat stops

Common Query Parameters​

Many list endpoints support:

ParameterTypeDefaultDescription
qstring-Full-text search query (searches name, description)
sortstringnameSort field (prefix with - for descending)
limitinteger30Results per page
startinteger0Pagination offset

Error Responses​

Standard HTTP status codes:

  • 200 - Success
  • 201 - Created (resource created successfully)
  • 204 - No Content (successful delete)
  • 400 - Bad request (validation error)
  • 403 - Forbidden (insufficient permissions)
  • 404 - Resource not found
  • 409 - Conflict (duplicate, constraint violation)
  • 500 - Internal server error

Long-Running Operations​

Several endpoints support long-running operations:

  • POST /api/jobs/{id} - Run job immediately (may take minutes/hours)
  • POST /api/jobs/{id}/actions/{actionId}/_preview - Preview action execution

Next Steps​

Explore the specific endpoint categories: