> For the complete documentation index, see [llms.txt](https://knowledgebase.fabricdata.com/studio/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://knowledgebase.fabricdata.com/studio/integrations-and-apis/origin-studio-production-api/background-jobs.md).

# Background Jobs

Long-running operations, such as record imports, contributor deletes and data delivery exports. Poll a job to follow its status.

## List background jobs

> Lists the caller's own background jobs, newest first by default. A browser user sees the jobs they started; an API key sees the jobs started with that key. Use \`filter.author.id\` to list another author's jobs.

```json
{"openapi":"3.0.3","info":{"title":"Fabric API - Audit","version":"0.9.2817"},"tags":[{"name":"Background Jobs","description":"Long-running operations, such as record imports, contributor deletes and data delivery exports. Poll a job to follow its status."}],"servers":[{"url":"{protocol}://{domain}/{basePath}","variables":{"protocol":{"enum":["http","https"],"default":"https"},"domain":{"default":"api.studio.fabricdata.com"},"basePath":{"default":"v1"}}}],"security":[{"jwt-apikey-authorizer":[]}],"components":{"securitySchemes":{"jwt-apikey-authorizer":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"BackgroundJobFindManyResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IBackgroundJobFindManyResponse","description":"One page of background jobs in the caller's tenant.","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["backgroundJobs"]},"attributes":{"$ref":"#/components/schemas/BackgroundJobAttributes"},"links":{"type":"object","properties":{"self":{"type":"string"}},"additionalProperties":false},"relationships":{"type":"object","properties":{"tenant":{"$ref":"#/components/schemas/TenantRelationship"},"author":{"$ref":"#/components/schemas/UserRelationship"}},"additionalProperties":false}},"required":["id","type","attributes"],"additionalProperties":false}},"meta":{"type":"object","properties":{"cursor":{"type":"string","description":"Pass as `page.cursor` to get the next page."}},"additionalProperties":false},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}},"required":["data","jsonapi"],"additionalProperties":false},"BackgroundJobAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IBackgroundJobAttributes","description":"Attributes of a background job, a long-running operation such as a contributor delete or tenant data export. They carry the status, job type and parameters, plus the output on completion, error details on failure, and item counts for batch jobs.","type":"object","allOf":[{"$ref":"#/components/schemas/BaseResourceAttributes"},{"type":"object","properties":{"type":{"type":"string"},"parameters":{"type":"object"},"status":{"$ref":"#/components/schemas/BackgroundJobStatus"},"output":{"type":"object","properties":{"errorsAvailable":{"type":"boolean","description":"True when GET /backgroundJobs/{jobId}/errors can download the job's per-item error files."}}},"totalItemsCount":{"type":"integer","minimum":0,"description":"Total items in a batch job, when applicable."},"successItemsCount":{"type":"integer","minimum":0,"description":"Items the batch job processed successfully, when applicable."},"failedItemsCount":{"type":"integer","minimum":0,"description":"Items that failed in a batch job, when applicable."},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message","code"],"additionalProperties":false}},"required":["type","parameters","status"],"additionalProperties":false}],"additionalProperties":false},"BaseResourceAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IBaseResourceAttributes","description":"Timestamps on every resource's attributes, as ISO 8601 date-times. `created` marks the resource's creation; `updated` marks its last change.","type":"object","additionalProperties":false,"required":["created","updated"],"properties":{"created":{"type":"string","format":"date-time"},"updated":{"type":"string","format":"date-time"}}},"BackgroundJobStatus":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IBackgroundJobStatus","description":"A background job's status. `RUNNING` and `PENDING_REDRIVE` (queued for retry) are still in progress; `SUCCEEDED`, `FAILED`, `TIMED_OUT` and `ABORTED` are final.","type":"string","enum":["ABORTED","FAILED","PENDING_REDRIVE","RUNNING","SUCCEEDED","TIMED_OUT"]},"TenantRelationship":{"$schema":"http://json-schema.org/draft-07/schema#","title":"ITenantRelationship","description":"A relationship to a tenant","type":"object","properties":{"data":{"additionalProperties":false,"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["tenants"]}},"required":["id","type"]},"links":{"$ref":"#/components/schemas/LinksRelated"}},"required":["data","links"],"additionalProperties":false},"LinksRelated":{"$schema":"http://json-schema.org/draft-07/schema#","title":"ILinks","description":"A JSON:API links object with an absolute or relative 'related' link","type":"object","required":["related"],"properties":{"related":{"type":"string"}},"additionalProperties":false},"UserRelationship":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IUserRelationship","description":"A relationship to the actor behind a write, such as `author` or `updatedBy`. `data.meta.type` is the actor type: a human user, an API key or an internal service. Only human users carry `links.related`.","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["users"]},"meta":{"type":"object","properties":{"tenantId":{"type":"string"},"type":{"type":"string"},"displayName":{"type":"string"}},"required":["tenantId","type","displayName"],"additionalProperties":false}},"required":["id","type","meta"],"additionalProperties":false},"links":{"$ref":"#/components/schemas/LinksRelated"}},"required":["data"],"additionalProperties":false},"JsonApiVersion":{"type":"object","description":"The JSON:API version this document conforms to.","properties":{"version":{"type":"string"}},"required":["version"],"additionalProperties":false},"ErrorResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IErrorResponse","description":"The body of a failed request: an `errors` array with one or more error objects.","type":"object","required":["errors","jsonapi"],"additionalProperties":false,"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"Error":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IError","description":"One JSON:API error object. `status` is the HTTP status code as a string, `title` a short summary and `detail` optional context. `meta` can carry structured conflict or authorization details.","type":"object","additionalProperties":false,"required":["status","title"],"properties":{"status":{"type":"string"},"title":{"type":"string"},"code":{"type":"string","description":"A stable code for the problem that you can act on, when the operation documents one."},"detail":{"type":"string"},"source":{"type":"object","description":"A JSON Pointer to the request field that caused the error, such as `/data/attributes/title`.","properties":{"pointer":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true,"properties":{"stack":{"type":"string","description":"The error's stack trace. Non-production environments only."},"conflictItems":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"unauthorizedItems":{"type":"array","items":{"type":"string"}}}}}}}},"paths":{"/backgroundJobs":{"get":{"summary":"List background jobs","operationId":"backgroundJobFindMany","description":"Lists the caller's own background jobs, newest first by default. A browser user sees the jobs they started; an API key sees the jobs started with that key. Use `filter.author.id` to list another author's jobs.","tags":["Background Jobs"],"parameters":[{"name":"filter.type","description":"Narrows the listed author's jobs to one job type, such as `deleteContributor` or `deleteRecord`.","in":"query","required":false,"schema":{"type":"string","minLength":1}},{"name":"filter.author.id","description":"Lists this author's jobs instead of the caller's own. Use the id from a job's `author` relationship. You need tenant administration rights to list another author's jobs; otherwise the API answers `403`.","in":"query","required":false,"schema":{"type":"string","minLength":1}},{"name":"sort","description":"The field to sort by. Prefix it with `-` to sort descending.","in":"query","required":false,"schema":{"type":"string","enum":["created","-created"]}},{"name":"page.cursor","description":"The previous page's `meta.cursor`.","in":"query","required":false,"schema":{"type":"string"}},{"name":"page.size","description":"Jobs per page. Defaults to 20; maximum 50.","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}],"responses":{"200":{"description":"One page of background jobs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BackgroundJobFindManyResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Background job status temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Get a background job by ID

> Gets one background job. Refreshes its status while the job is still running.

```json
{"openapi":"3.0.3","info":{"title":"Fabric API - Audit","version":"0.9.2817"},"tags":[{"name":"Background Jobs","description":"Long-running operations, such as record imports, contributor deletes and data delivery exports. Poll a job to follow its status."}],"servers":[{"url":"{protocol}://{domain}/{basePath}","variables":{"protocol":{"enum":["http","https"],"default":"https"},"domain":{"default":"api.studio.fabricdata.com"},"basePath":{"default":"v1"}}}],"security":[{"jwt-apikey-authorizer":[]}],"components":{"securitySchemes":{"jwt-apikey-authorizer":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"BackgroundJobFindOneResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IBackgroundJobFindOneResponse","description":"A single background job.","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["backgroundJobs"]},"attributes":{"$ref":"#/components/schemas/BackgroundJobAttributes"},"links":{"type":"object","properties":{"self":{"type":"string"}},"additionalProperties":false},"relationships":{"type":"object","properties":{"tenant":{"$ref":"#/components/schemas/TenantRelationship"},"author":{"$ref":"#/components/schemas/UserRelationship"}},"additionalProperties":false}},"required":["id","type","attributes"],"additionalProperties":false},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}},"required":["data","jsonapi"],"additionalProperties":false},"BackgroundJobAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IBackgroundJobAttributes","description":"Attributes of a background job, a long-running operation such as a contributor delete or tenant data export. They carry the status, job type and parameters, plus the output on completion, error details on failure, and item counts for batch jobs.","type":"object","allOf":[{"$ref":"#/components/schemas/BaseResourceAttributes"},{"type":"object","properties":{"type":{"type":"string"},"parameters":{"type":"object"},"status":{"$ref":"#/components/schemas/BackgroundJobStatus"},"output":{"type":"object","properties":{"errorsAvailable":{"type":"boolean","description":"True when GET /backgroundJobs/{jobId}/errors can download the job's per-item error files."}}},"totalItemsCount":{"type":"integer","minimum":0,"description":"Total items in a batch job, when applicable."},"successItemsCount":{"type":"integer","minimum":0,"description":"Items the batch job processed successfully, when applicable."},"failedItemsCount":{"type":"integer","minimum":0,"description":"Items that failed in a batch job, when applicable."},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message","code"],"additionalProperties":false}},"required":["type","parameters","status"],"additionalProperties":false}],"additionalProperties":false},"BaseResourceAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IBaseResourceAttributes","description":"Timestamps on every resource's attributes, as ISO 8601 date-times. `created` marks the resource's creation; `updated` marks its last change.","type":"object","additionalProperties":false,"required":["created","updated"],"properties":{"created":{"type":"string","format":"date-time"},"updated":{"type":"string","format":"date-time"}}},"BackgroundJobStatus":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IBackgroundJobStatus","description":"A background job's status. `RUNNING` and `PENDING_REDRIVE` (queued for retry) are still in progress; `SUCCEEDED`, `FAILED`, `TIMED_OUT` and `ABORTED` are final.","type":"string","enum":["ABORTED","FAILED","PENDING_REDRIVE","RUNNING","SUCCEEDED","TIMED_OUT"]},"TenantRelationship":{"$schema":"http://json-schema.org/draft-07/schema#","title":"ITenantRelationship","description":"A relationship to a tenant","type":"object","properties":{"data":{"additionalProperties":false,"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["tenants"]}},"required":["id","type"]},"links":{"$ref":"#/components/schemas/LinksRelated"}},"required":["data","links"],"additionalProperties":false},"LinksRelated":{"$schema":"http://json-schema.org/draft-07/schema#","title":"ILinks","description":"A JSON:API links object with an absolute or relative 'related' link","type":"object","required":["related"],"properties":{"related":{"type":"string"}},"additionalProperties":false},"UserRelationship":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IUserRelationship","description":"A relationship to the actor behind a write, such as `author` or `updatedBy`. `data.meta.type` is the actor type: a human user, an API key or an internal service. Only human users carry `links.related`.","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["users"]},"meta":{"type":"object","properties":{"tenantId":{"type":"string"},"type":{"type":"string"},"displayName":{"type":"string"}},"required":["tenantId","type","displayName"],"additionalProperties":false}},"required":["id","type","meta"],"additionalProperties":false},"links":{"$ref":"#/components/schemas/LinksRelated"}},"required":["data"],"additionalProperties":false},"JsonApiVersion":{"type":"object","description":"The JSON:API version this document conforms to.","properties":{"version":{"type":"string"}},"required":["version"],"additionalProperties":false},"ErrorResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IErrorResponse","description":"The body of a failed request: an `errors` array with one or more error objects.","type":"object","required":["errors","jsonapi"],"additionalProperties":false,"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"Error":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IError","description":"One JSON:API error object. `status` is the HTTP status code as a string, `title` a short summary and `detail` optional context. `meta` can carry structured conflict or authorization details.","type":"object","additionalProperties":false,"required":["status","title"],"properties":{"status":{"type":"string"},"title":{"type":"string"},"code":{"type":"string","description":"A stable code for the problem that you can act on, when the operation documents one."},"detail":{"type":"string"},"source":{"type":"object","description":"A JSON Pointer to the request field that caused the error, such as `/data/attributes/title`.","properties":{"pointer":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true,"properties":{"stack":{"type":"string","description":"The error's stack trace. Non-production environments only."},"conflictItems":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"unauthorizedItems":{"type":"array","items":{"type":"string"}}}}}}}},"paths":{"/backgroundJobs/{jobId}":{"get":{"summary":"Get a background job by ID","operationId":"backgroundJobFindOne","description":"Gets one background job. Refreshes its status while the job is still running.","tags":["Background Jobs"],"parameters":[{"name":"jobId","description":"The job to get.","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The background job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BackgroundJobFindOneResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Background job status temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
