Scheduling & Job Status

FreshShots lets you programmatically trigger screenshot workflows and monitor their execution status. This guide covers scheduling automated updates and tracking job progress.

🔧 API Endpoint

To trigger a screenshot workflow:

curl -X POST https://api.freshshots.io/v1/run/{workflow_id} \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://your-server.com/webhook"
  }'

You can also find the workflow id from within the “Advanced Editor” tab.

Scroll to the bottom for personalized info on how to trigger each workflow.

🔁 Replace:

{workflow_id} with your actual workflow ID
YOUR_API_KEY_HERE with your FreshShots API key
webhook_url with the URL to receive screenshot completion data (optional)

If you don’t need a webhook, you can omit the -d flag entirely.

Job Status Monitoring

After triggering a workflow, you can monitor its execution status:

Check Job Status

curl -X GET https://api.freshshots.io/v1/job/{job_id}/status \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json"

Job Status Values

queued - Job is waiting to be processed
running - Job is currently being executed
completed - Job finished successfully
failed - Job encountered an error
aborted - Job was manually stopped

When to Schedule Updates

Common scheduling patterns:

Weekly UI changes - Every Monday at 9AM
Monthly reporting - 1st of each month
Pre-deployment checks - Before every release
Daily monitoring - Every morning for critical pages

🛠️ How to Schedule the API Call

You can use tools like:

📅 Linux Cron

Edit your crontab:

crontab -e

Add a line like:

0 9 * * 1 curl -X POST https://api.freshshots.io/v1/run/23 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

This example runs every Monday at 9:00 AM.

⏱️ GitHub Actions

Use schedule and curl:

name: FreshShots Weekly Screenshots

on:
    schedule:
        - cron: "0 9 * * 1" # Every Monday at 9AM UTC

jobs:
    trigger-freshshots:
        runs-on: ubuntu-latest
        steps:
            - name: Trigger Screenshot Workflow
              run: |
                  curl -X POST https://api.freshshots.io/v1/run/23 \
                    -H "x-api-key: ${{ secrets.FRESHSHOTS_API_KEY }}" \
                    -H "Content-Type: application/json"

☁️ Serverless Schedulers

Works great with:

AWS Lambda + EventBridge (Cron)
Google Cloud Scheduler
Zapier / Make / n8n
UptimeRobot / cron-job.org

Just configure them to make the POST request on your desired interval.

📬 Webhook Integration (Optional)

Set a webhook_url in the API call to be notified when screenshots are ready.

You’ll receive a POST request like this:

{
	"workflow_id": "23",
	"status": "completed",
	"screenshots": [
		{
			"id": "abc123",
			"cdn_url": "https://cdn.freshshots.io/screenshots/..."
		}
	]
}

✅ Best Practices

🗂 Use descriptive workflow names (e.g., Weekly Docs UI)
🔐 Keep your API key secret (use environment variables or secrets management)
🧪 Test your schedule with a manual trigger first
📁 Store or display results using the returned CDN URLs

Need Help?

We’re happy to help set up automated screenshot updates. Reach us at [email protected].

Documentation