Jobs

Every render, whatever produced it. Job history is product-agnostic: image rendering and conversion will appear here unchanged.

List jobs, newest first

gethttps://api.paperpony.dev/v1/jobs

Cursor pagination, never offset: a job created while you page through cannot shift the window and hide a result.

Parameters

Name	In	Description
`limit`	query
`cursor`	query	The `next_cursor` from the previous page. Opaque.
`status`	query
`product`	query

Example

curlJavaScriptPython

curl https://api.paperpony.dev/v1/jobs?limit=20&status=succeeded \
  -H "Authorization: Bearer $PAPERPONY_API_KEY"

import { PaperPony } from 'paperpony';

const pony = new PaperPony({ apiKey: process.env.PAPERPONY_API_KEY });

const page = await pony.jobs.list({ limit: 20, status: 'succeeded' });

for (const job of page.data) console.log(job.id, job.credits_charged);
if (page.next_cursor) await pony.jobs.list({ cursor: page.next_cursor });

import os
import requests

response = requests.get(
    "https://api.paperpony.dev/v1/jobs?limit=20&status=succeeded",
    headers={"Authorization": f"Bearer {os.environ['PAPERPONY_API_KEY']}"},
)
response.raise_for_status()
print(response.json())

Returns

listJobs response
Field	Type	Description
`data`required	`object[]`
`has_more`required	`boolean`
`next_cursor`required	`string \| null`

Responses

Status	Code	Meaning
`200`		A page of jobs.
`401`	unauthorized · invalid_api_key	No credential, or the credential is malformed, unknown or revoked.
`422`	invalid_request	The body or the query failed validation. The message names the field.
`429`	rate_limited	Too many requests. Authenticated routes count per account, never per key.
`500`	internal_error	Unexpected failure. Quote request_id when reporting it.

Job status and result

gethttps://api.paperpony.dev/v1/jobs/{id}

output_url is signed fresh on every read, so a link you fetch on day six still works, for as long as the object itself lives, which is the plan's retention.

Parameters

Name	In	Description
`id`required	path

Example

curlJavaScriptPython

curl https://api.paperpony.dev/v1/jobs/job_01JZ3M8Q0000000000000000CD \
  -H "Authorization: Bearer $PAPERPONY_API_KEY"

import { PaperPony } from 'paperpony';

const pony = new PaperPony({ apiKey: process.env.PAPERPONY_API_KEY });

const job = await pony.jobs.get('job_01JZ3M8Q0000000000000000CD');
console.log(job.status);

import os
import requests

response = requests.get(
    "https://api.paperpony.dev/v1/jobs/job_01JZ3M8Q0000000000000000CD",
    headers={"Authorization": f"Bearer {os.environ['PAPERPONY_API_KEY']}"},
)
response.raise_for_status()
print(response.json())

Returns

getJob response
Field	Type	Description
`id`required	`string`
`status`required	`"queued" \| "processing" \| "succeeded" \| "failed"`
`product`required	`string`
`mode`required	`"sync" \| "async"`
`template_id`required	`string \| null`
`output_url`required	`string \| null`	Signed and expiring, never permanent. Signed fresh on every read of the job.
`output_bytes`required	`integer \| null`
`output_expires_at`required	`string \| null`	When the object itself is deleted, from the plan's retention.date-time
`page_count`required	`integer \| null`
`credits_charged`required	`integer`
`credits_remaining`required	`integer`
`watermarked`required	`boolean`
`error`required	`object \| null`
`code`required	`string`
`message`required	`string`
`created_at`required	`string`	date-time
`started_at`required	`string \| null`	date-time
`finished_at`required	`string \| null`	date-time

Responses

Status	Code	Meaning
`200`		The job.
`401`	unauthorized · invalid_api_key	No credential, or the credential is malformed, unknown or revoked.
`404`	job_not_found	No route matches the path (not_found), or the resource does not exist on this account (template_not_found, job_not_found).
`422`	invalid_request	The body or the query failed validation. The message names the field.
`429`	rate_limited	Too many requests. Authenticated routes count per account, never per key.
`500`	internal_error	Unexpected failure. Quote request_id when reporting it.

Every error uses one envelope, and every response carries an X-Request-Id. Quote it if you report a problem.