Skip to main content

Job API Overview

Looking for the product view?
The Help Center explains this surface as users see it: Working with Jobs.

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. A job is readable by its owner, by every member of its owning team (at any role), and by superusers. Every /api/jobs/{id} route answers 404 for a job the caller cannot read, as if it did not exist.
  • Edit permission - job:edit (Data Wizard or higher in the owning team, the owning user, or a superuser) is required for every change to a job's configuration: the job itself, drafts and commits, actions, attachments, run conditions, file contents, datasets, history and action order. A caller who can read but not edit a job gets 403.
  • 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 - Recurrence expression, in the shape the interval type expects (e.g., "0 0 * * *" for daily at midnight). null for a one-time Job.
  • intervalType - One of Once, Minutes, Hourly, Daily, Weekly, Monthly, Yearly, Custom
  • 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: