Skip to main content
GET
List jobs
Requires the job:read scope. Requests without this scope receive a 403 FORBIDDEN response. See authentication.
Jobs are returned newest-first (created_at descending) and scoped to your account. Use limit (max 100) and offset to page through results; total in the response is the unpaginated count.

Filters

API key attribution

Each job submitted with an API key records that key. Each row in the response carries api_key_id and api_key_name, so you can split traffic by key. For example, you can use one key per environment, customer, or service without keeping your own mapping. Both fields are null on a job that no key submitted: one sent from the dashboard, and any job created before key attribution shipped. Filter to exactly those with api_key_id=none. api_key_name is resolved when you read the job, not stored on it. A key you renamed shows its current name on every past job, and a key you deleted resolves to null. api_key_id is stored on the job and never changes, so it stays correct in both cases. Use the id as the stable identifier.

Status filter

status accepts a comma-separated list of one or more job statuses: A moderation job stays queued for its whole run and then flips straight to completed or failed; it never reports processing. queued and processing are both in-flight states and completed and failed are terminal, so request both in-flight values to stay correct if that changes:
An unknown status value returns 400 INVALID_REQUEST.

Polling for completion

Webhooks are the primary, low-latency way to learn that a job finished. Register one when you submit, or via register webhook. Webhook delivery is best-effort, so use this endpoint as a cheap reconciliation safety net rather than your primary signal:
  • Poll GET /api/v1/jobs?status=queued,processing on an interval. One request covers every outstanding job, regardless of how many you have in flight. That is far cheaper than polling each job individually with get job status.
  • A job that drops out of the in-flight list has reached a terminal state. Fetch the terminal set (status=completed,failed, optionally narrowed with from) to pick up any outcome whose webhook was missed.
  • Keep the interval modest. Every request counts toward your rate limit. Webhooks carry the fast path; reconciliation only needs to catch stragglers.

Example

Authorizations

Authorization
string
header
required

API key from the Omnifence dashboard

Query Parameters

limit
integer
default:50
Required range: 1 <= x <= 100
offset
integer
default:0
Required range: x >= 0
type
enum<string>

Filter by job modality. text, image, video, audio are the active moderation modalities. generate and pre/post/chat are non-moderation or retired types, kept so historical jobs stay filterable.

Available options:
pre,
post,
chat,
text,
image,
video,
audio,
generate
decision
enum<string>

Filter by moderation decision.

Available options:
pass,
reject
status
string

Filter by job status. Comma-separated list of: queued, processing, completed, failed. Example: status=queued,processing returns all in-flight jobs, which is useful for low-cost reconciliation polling alongside webhooks.

Prefix-match filter on job_id.

Maximum string length: 64
api_key_id
string

Filter to jobs submitted with a single API key. Pass the key id, or the literal none to return only the jobs with no key attribution (dashboard submissions and jobs created before key attribution shipped).

Maximum string length: 128
from
string<date-time>

Inclusive lower bound on job created_at (ISO 8601).

to
string<date-time>

Exclusive upper bound on job created_at (ISO 8601).

Response

200 - application/json

Default Response

jobs
object[]
required
total
integer
required
limit
integer
required
offset
integer
required