Skip to main content
GET
/
api
/
v1
/
jobs
List jobs
curl --request GET \
  --url http://localhost:3051/api/v1/jobs \
  --header 'Authorization: Bearer <token>'
{
  "jobs": [
    {
      "job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "is_prohibited": true,
      "created_at": "2023-11-07T05:31:56Z",
      "completed_at": "2023-11-07T05:31:56Z"
    }
  ],
  "total": 123,
  "limit": 123,
  "offset": 123
}

Documentation Index

Fetch the complete documentation index at: https://docs.omnifence.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

ParameterDescription
typeJob modality — prompt, image, or video (pre/post are legacy).
decisionModeration outcome — pass or reject.
statusJob status — see below.
searchPrefix-match on job_id.
fromInclusive lower bound on created_at (ISO 8601).
toExclusive upper bound on created_at (ISO 8601).

​
Status filter

status accepts a comma-separated list of one or more job statuses:
StatusMeaning
queuedAccepted, waiting for a worker.
processingRunning through the moderation pipeline.
completedFinished — see is_prohibited for the outcome.
failedTerminated with an error before a decision.
queued and processing are the in-flight states; completed and failed are terminal. To list every job still in flight, request both: 
GET /api/v1/jobs?status=queued,processing
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 — 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

curl -G "https://api.evershield.ai/api/v1/jobs" \
  -H "Authorization: Bearer $API_KEY" \
  --data-urlencode "status=queued,processing" \
  --data-urlencode "limit=100"

Authorizations

​
Authorization
string
header
required

API key from the Stars 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. prompt, image, video are the active modalities; pre/post are legacy types kept for historical jobs.

Available options:
pre,
post,
prompt,
image,
video
​
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 — useful for low-cost reconciliation polling alongside webhooks.

​
search
string

Prefix-match filter on job_id.

Maximum string length: 64
​
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