Background tasks (jobs) with automatic retries
Hand slow or unreliable work to a background job that retries on its own, and watch its status in the Console.
A job is a single piece of work that runs in the background. Your app asks for it and moves on, instead of making the person wait. If it fails, PGB retries it automatically with growing delays. In the Console this page is called Tasks in the sidebar and Background Tasks at the top of the page.
When to use a job
Use a job for anything that should not block a request: sending a welcome email after sign-up, resizing an uploaded image, syncing to another service. You do not create a queue or write a consumer. If you need several independent workers or custom delivery tuning, use a queue instead. If the work should repeat on a schedule, use Cron Jobs.
Enqueue a job
A job has a job type (a name you choose), a target (what runs) and a payload (the data). The target can be a function, a webhook, sql, a queue, mail, an event, a realtime broadcast, a container or an action.
From your server, with your secret key:
curl -X POST https://my-project.pgbhub.app/api/v1/projects/my-project/jobs \
-H "Authorization: Bearer pgb_sec_..." -H "Content-Type: application/json" \
-d '{"job_type": "send_welcome_email", "target_type": "function",
"target_config": {"function_name": "sendWelcomeEmail"},
"payload": {"email": "[email protected]"}, "max_attempts": 3}'
Or with the TypeScript SDK, admin.jobs.enqueue(...), then get(id), list() and cancel(id).
Useful options:
max_attempts: how many tries before giving up. The default is 5, and the allowed range is 1 to 20.idempotency_key: a value that makes sure the same job is not created twice if your app retries the request.
Watch jobs in the Console
Open Tasks. The table shows each job's ID, Job Type, Target, Status, Attempts (for example 2/5), Next Attempt and Last Error.
| Status | Meaning |
|---|---|
| Pending | Waiting to run, or waiting for the next retry |
| Running | In progress |
| Done | Finished successfully |
| Dead-lettered | Failed every attempt. It stays here so you can see why |
| Cancelled | You cancelled it before it ran |
A banner shows how many jobs are dead-lettered. For a pending job, choose Cancel to stop it.
How retries work
When a job fails, it waits and tries again, doubling the delay each time starting at one second, up to a maximum of five minutes. After the last attempt it is marked dead-lettered. Make sure your function is safe to run twice, because a retry can happen after a partial success.
Good to know
- You cannot enqueue a job whose target is another job. This stops a job from creating endless jobs.
- If your account is paused, new jobs are refused with a clear message.
- Jobs count toward your project's usage. See Pricing for current rates.
More guides in Console: functions, cron & jobs
Create and deploy a function
Write a function in the Console editor, choose a runtime and trigger, test it, and call it over HTTP.
Function secrets, webhooks and logs
Keep keys out of your code, protect a function with a signed webhook, and read or limit its execution logs.
Schedule work with Cron Jobs
Run a function, SQL, an action, an HTTP call or an email on a schedule, and read the run history.
Actions: named transactions with effects
Define a named SQL transaction once, call it from your app, an AI agent or a schedule, and trigger emails, queues and more after it commits.