> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quedup.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Concepts
> Learn how QuedUp works and its core features
# QuedUp Concepts
Understanding the core concepts of QuedUp will help you make the most of the platform and design reliable job workflows.
## How QuedUp Works
QuedUp operates on a simple but powerful model:
1. **Job Definition**: You define a job with a URL, HTTP method, and scheduling information
2. **Scheduling**: QuedUp stores your job and calculates when it should run next
3. **Execution**: At the scheduled time, QuedUp makes an HTTP request to your endpoint
4. **Monitoring**: You can track job runs, view responses, and monitor status
When you create a job, QuedUp validates your configuration and stores it in our system. The job is immediately scheduled for execution.
Based on your schedule or run\_at time, QuedUp calculates the next execution time and queues the job.
At the scheduled time, QuedUp makes an HTTP request to your endpoint with the specified method, headers, and body.
QuedUp captures the response status, headers, and body for logging and monitoring purposes.
If the job fails, QuedUp automatically retries with exponential backoff according to our retry policy.
QuedUp is built on a distributed architecture designed for reliability and scalability:
* **Scheduler**: Manages job scheduling and timing
* **Executor**: Handles HTTP request execution
* **Storage**: Persists jobs and run history
* **Monitoring**: Tracks job status and performance
## Core Features
### Automatic Retries
QuedUp automatically retries failed jobs to ensure reliability. Retries are triggered by:
* **Network errors**: Connection timeouts, DNS failures, etc.
* **Timeouts**: If your endpoint takes longer than 15 minutes to respond.
* **Non-2xx Status Codes**: Any HTTP response code other than 200-299 (e.g., 404, 500, 503).
| Attempt | Delay | Description |
| :------ | :---------- | :------------------------ |
| 1 | Immediate | Initial execution |
| 2 | Immediate | Immediate retry (0 delay) |
| 3 | +5 minutes | First delayed retry |
| 4 | +15 minutes | Second delayed retry |
| 5 | +1 hour | Third delayed retry |
| 6 | +3 hours | Fourth delayed retry |
| 7 | +6 hours | Final attempt |
**Total Attempts**: 7 (1 initial + 6 retries).
After all retries are exhausted, the job run is marked as `failed`. For recurring jobs, this does not affect future scheduled runs.
### Comprehensive Logging
Every job run is logged with detailed information:
* **Request Details**: URL, method, headers, body
* **Response Details**: Status code, headers, response body
* **Timing Information**: Start time, duration, retry attempts
* **Error Information**: Error messages and stack traces (if applicable)
### Job States
Jobs can be in one of several states:
* **`active`**: Job is scheduled and will run at the next scheduled time
* **`paused`**: Job is temporarily disabled and won't execute
* **`completed`**: One-time job has finished successfully
* **`failed`**: Job has failed and won't retry (recurring jobs remain active)
* **`pending`**: Job is queued for execution
* **`running`**: Job is currently executing
* **`success`**: Job completed successfully
* **`failed`**: Job failed (may retry based on configuration)
## Scheduling
### Cron Expressions
Recurring jobs use standard cron expressions with 5 fields:
```
┌───────────── minute (0 - 59)
│ ┌─────────── hour (0 - 23)
│ │ ┌───────── day of month (1 - 31)
│ │ │ ┌─────── month (1 - 12)
│ │ │ │ ┌───── day of week (0 - 6) (Sunday to Saturday)
│ │ │ │ │
* * * * *
```
```bash Common Cron Examples theme={null}
# Every minute
* * * * *
# Every hour at minute 0
0 * * * *
# Every day at 2 AM
0 2 * * *
# Every Monday at 9 AM
0 9 * * 1
# Every first day of the month at midnight
0 0 1 * *
```
### One-time Jobs
One-time jobs use RFC3339 timestamps:
* **Format**: `2024-01-15T10:00:00Z`
* **Timezone**: Always UTC
* **Past Times**: Jobs scheduled in the past will run immediately
## Security
### API Keys
All API requests require authentication via API key:
* **Header**: `Authorization: Bearer YOUR_API_KEY`
* **Scope**: Full access to your organization's jobs
* **Rotation**: You can generate new keys and delete old ones in the dashboard.
### HTTPS Only
* All job endpoints must use HTTPS
* HTTP endpoints are rejected for security
* Self-signed certificates are supported
### Request Validation
QuedUp validates all incoming requests:
* **URL Format**: Must be a valid HTTPS URL
* **Method**: Must be a valid HTTP method (GET, POST, PUT, PATCH, DELETE)
* **Schedule**: Cron expressions must be valid
* **Timestamps**: Must be valid RFC3339 format
## Limits
To ensure platform stability and fair usage, the following limits apply:
| Limit Type | Value | Description |
| :--------------------- | :--------- | :----------------------------------------------------- |
| **Daily Executions** | 100 | Maximum number of job runs per organization per day. |
| **Monthly Executions** | 2,000 | Maximum number of job runs per organization per month. |
| **Execution Timeout** | 15 minutes | Maximum duration a job can run before being timed out. |
| **Response Body** | 10 MB | Maximum size of the response body stored in logs. |
## Monitoring & Observability
### Job Monitoring
Track your jobs in real-time:
* **Status Dashboard**: View all jobs and their current status
* **Run History**: Detailed logs of every job execution
* **Performance Metrics**: Response times and success rates
* **Error Tracking**: Failed jobs with error details
### Webhooks (Coming Soon)
Get notified of job events:
* **Job Started**: When a job begins execution
* **Job Completed**: When a job finishes successfully
* **Job Failed**: When a job fails after all retries
## Best Practices
### Job Design
* **Idempotent**: Design your endpoints to be idempotent
* **Timeout Handling**: Ensure your endpoints respond within reasonable time
* **Error Handling**: Return appropriate HTTP status codes
* **Logging**: Log important events in your application
### Scheduling
* **Avoid Overlap**: Don't schedule jobs too frequently to prevent overlap
* **Time Zones**: Always use UTC for scheduling
* **Testing**: Test your schedules with one-time jobs first
### Monitoring
* **Regular Checks**: Monitor your job runs regularly
* **Alerting**: Set up alerts for failed jobs (coming soon)
* **Metrics**: Track success rates and response times
Explore different job configurations
Create your first job