> ## Documentation Index > Fetch the complete documentation index at: https://docs.strait.dev/llms.txt > Use this file to discover all available pages before exploring further. # Jobs > The fundamental unit of work in Strait. Jobs define the configuration for a specific task that can be executed. They act as templates for **Runs**. ## Job Model The `Job` struct (defined in `apps/strait/internal/domain/types.go`) contains the following fields: | Field | Type | Description | | :----------------------------- | :------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `string` | Unique identifier (UUIDv7). | | `project_id` | `string` | The project this job belongs to. | | `group_id` | `string` | Optional ID of the `JobGroup` for logical organization. | | `name` | `string` | Human-readable name of the job. | | `slug` | `string` | URL-friendly identifier, unique within a project. | | `description` | `string` | Optional detailed description. | | `cron` | `string` | 5-field cron expression for automatic scheduling. | | `cron_overlap_policy` | `string` | Behavior when a cron tick fires with active runs: `allow` (default), `skip`, or `cancel_running`. See [Scheduling](/concepts/scheduling). | | `payload_schema` | `json` | JSON Schema to validate incoming trigger payloads. | | `tags` | `map[string]string` | Key-value pairs for filtering and metadata. | | `endpoint_url` | `string` | The primary HTTP URL where the job payload is sent. | | `fallback_endpoint_url` | `string` | Optional URL used if the primary endpoint fails. | | `max_attempts` | `int` | Maximum number of retry attempts (default: 3). | | `timeout_secs` | `int` | Maximum execution time in seconds (default: 300). | | `max_concurrency` | `int` | Per-job limit on simultaneous executing runs. | | `execution_window_cron` | `string` | Cron-like expression defining when the job is allowed to run. | | `timezone` | `string` | Timezone for cron scheduling (e.g., "UTC", "America/New\_York"). | | `rate_limit_max` | `int` | Maximum number of runs allowed in the rate limit window. | | `rate_limit_window_secs` | `int` | The window size for rate limiting in seconds. | | `max_concurrency_per_key` | `int` | Per-key concurrency limit. When set with a run's `concurrency_key`, limits concurrent active runs sharing the same key. | | `rate_limit_keys` | `[]RateLimitKey` | Named rate limit configurations. Each entry has `name`, `max`, and `window_secs`. | | `default_run_metadata` | `map[string]string` | Default metadata key-value pairs applied to every run created for this job. | | `dedup_window_secs` | `int` | Window for deduplicating identical trigger requests. | | `enabled` | `bool` | Whether the job is active and can be triggered. | | `webhook_url` | `string` | URL to notify when a run reaches a terminal state. | | `webhook_secret` | `string` | Secret used to sign webhook payloads (HMAC-SHA256). | | `run_ttl_secs` | `int` | Time-to-live for runs before they are considered expired. | | `retry_strategy` | `string` | Strategy: `exponential`, `linear`, `fixed`, or `custom`. | | `retry_delays_secs` | `[]int` | Array of delays for the `custom` retry strategy. | | `poison_pill_threshold` | `*int` | Consecutive identical errors before auto-quarantine to DLQ. `null` or `0` disables. See [Resilience](/concepts/resilience#poison-pill-detection). | | `environment_id` | `string` | The environment (e.g., Staging, Production) this job is bound to. | | `version` | `int` | Auto-incrementing version number (starts at 1). | | `version_id` | `string` | Unique nanoid for this version (`ver_k8f2m9x1p3`). Changes on every update. | | `version_policy` | `string` | How queued runs interact with updates: `pin` (default), `latest`, or `minor`. See [Versioning](/concepts/versioning). | | `backwards_compatible` | `bool` | Whether the current version is backwards compatible with the previous version. | | `created_by` | `string` | Actor ID who created the job (user ID or `apikey:`). | | `updated_by` | `string` | Actor ID who last updated the job. | | `on_complete_trigger_workflow` | `string` | Optional workflow slug to auto-trigger when a run completes successfully. | | `on_complete_payload_mapping` | `json` | Optional JSON mapping to extract fields from the run result as the triggered workflow's payload. Uses dot-notation paths (e.g., `{"user_id": "result.user.id"}`). | | `created_at` | `time.Time` | Timestamp when the job was created. | | `updated_at` | `time.Time` | Timestamp of the last update. | ## Slugs and Project Scoping Jobs are scoped to a `project_id`. The `slug` must be unique within that project. This allows for clean URLs and API access patterns like `/v1/jobs/{jobID}`. ## Scheduling and Execution ```json Cron Scheduling theme={null} { "cron": "0 * * * *", "timezone": "UTC" } ``` ```json Execution Window theme={null} { "execution_window_cron": "0 9-17 * * 1-5" } ``` * **Cron**: Standard 5-field syntax supported via `robfig/cron/v3`. * **Execution Windows**: Restricts job execution to specific times (e.g., business hours). ## Concurrency and Rate Limiting * **Max Concurrency**: Limits the number of parallel executions for a single job definition. * **Rate Limiting**: Prevents thundering herds by capping the number of runs over a sliding window. * **Deduplication**: Uses `dedup_window_secs` and an idempotency key to ignore duplicate trigger requests within a short timeframe. ### Per-Key Concurrency When `max_concurrency_per_key` is set on a job, each run must provide a `concurrency_key`. Runs sharing the same key are limited to `max_concurrency_per_key` concurrent active executions. This is useful for per-tenant or per-resource throttling. For example, setting `max_concurrency_per_key: 1` ensures only one run per key executes at a time, creating a per-key serial queue. ### Named Rate Limit Keys The `rate_limit_keys` field allows defining multiple named rate limits on a single job. Each entry specifies: * `name`: identifier for the rate limit * `max`: maximum runs in the window * `window_secs`: window duration in seconds This extends the flat `rate_limit_max`/`rate_limit_window_secs` to support more granular control. ## Job Versioning Every time a job's configuration is updated, the `version` field is automatically incremented. This ensures that: 1. In-flight runs continue using the configuration they were triggered with. 2. Historical data remains accurate to the job's state at the time of execution. ## Webhook Configuration Jobs can be configured with a `webhook_url` and `webhook_secret`. When a run completes, fails, or times out, a signed POST request is sent to this URL. Always use the `webhook_secret` to verify webhook authenticity via `X-Strait-Signature` + `X-Strait-Timestamp` (and optionally compatibility `X-Webhook-Signature`). ## Environment Binding Jobs can be linked to an `environment_id`. This allows Strait to apply environment-specific overrides, such as changing the `endpoint_url` when running in a "Staging" vs "Production" environment. ## Related Concepts * [Runs](/concepts/runs): The execution instances of a job. * [Workflows](/concepts/workflows): DAGs that coordinate multiple jobs. * **Job Groups**: Logical containers for related jobs within a project.