> For the complete documentation index, see [llms.txt](https://docs.limio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.limio.com/api/catalog-api/catalog-jobs.md).

# Catalog Jobs

Queue work that is too large for one request, then read the job to learn where it got to. A job answers at once with an id and runs detached, so a caller queues it, does something else, and reads it later.

Use a job to import a file of items, to edit or copy many items at once, to export the catalog or the order data, to build a catalog in one step, or to rebuild the search index. To create or change one item, use Catalog Management, which answers when the work is done.

A job runs with the permissions of the caller who queued it. Reading a job takes the same permission as queueing it.

## List Catalog Jobs

> Lists the jobs of the last 24 hours, newest first. Older jobs are not listed.\
> \
> The list holds only the job types that you may queue, and it leaves out \`failedReason\`, which can be long. Read one job to get the reason it failed.

```json
{"openapi":"3.1.0","info":{"title":"Limio Commerce API","version":"1.0.0"},"tags":[{"name":"Catalog Jobs","description":"Queue work that is too large for one request, then read the job to learn where it got to. A job answers at once with an id and runs detached, so a caller queues it, does something else, and reads it later.\n\nUse a job to import a file of items, to edit or copy many items at once, to export the catalog or the order data, to build a catalog in one step, or to rebuild the search index. To create or change one item, use Catalog Management, which answers when the work is done.\n\nA job runs with the permissions of the caller who queued it. Reading a job takes the same permission as queueing it."}],"servers":[{"url":"https://{shard}.{domain}","variables":{"domain":{"default":"prod.limio.com"},"shard":{"default":"your-environment"}}}],"security":[{"bearerAuth":["catalog:write"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2.0 Bearer token for authenticated API access. Required for order submission, object management, and administrative operations.\n\nObtain a token via the OAuth flow described in [OAuth Bearer Token](https://docs.limio.com/developers/api-documentation/authentication-overview/oauth-bearer-token).\n\nPass the token in the `Authorization` header: `Bearer <token>`"}},"schemas":{"CatalogJob":{"type":"object","description":"A job, in the shape that a read returns.","properties":{"id":{"type":"string","description":"The id that the queue answered with."},"name":{"type":"string","description":"The job type, as it was queued."},"state":{"type":"string","description":"Where the job is. `waiting` and `delayed` mean it has not started, `active` means it is running, and `completed` and `failed` are final. `unknown` means the record does not settle a state.","enum":["waiting","delayed","active","paused","stuck","completed","failed","unknown"]},"progress":{"type":"number","description":"How far the job has run, as a percentage, when the job type reports it. Reads of a single job carry it; the list does not."},"message":{"type":"object","description":"A sentence for a person, written when the job finishes.","properties":{"notificationType":{"type":"string"},"message":{"type":"string"}}},"returnValue":{"type":"object","additionalProperties":true,"description":"What the job produced. An export puts the name of its file here, which is the name to ask for at `GET /limio/jobs/{id}/file/{filename}`."},"failedReason":{"type":"string","description":"Why the job failed. Only a read of a single job carries it: the reason can be long, so the list leaves it out."},"username":{"type":"string","description":"Who queued the job."},"data":{"type":"object","additionalProperties":true,"description":"The body that queued the job."},"processedOn":{"type":"number","description":"When the job started, in milliseconds since the epoch."},"timestamp":{"type":"number","description":"When the job was queued, in milliseconds since the epoch."}}}},"responses":{"401ApplicationResponse":{"description":"Unauthorized: the request lacks valid authentication credentials. Verify your Bearer token or API key is correct and has not expired.","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string","description":"The unique identifier of the request"},"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"paths":{"/limio/jobs":{"get":{"tags":["Catalog Jobs"],"operationId":"getCatalogJobs","summary":"List Catalog Jobs","description":"Lists the jobs of the last 24 hours, newest first. Older jobs are not listed.\n\nThe list holds only the job types that you may queue, and it leaves out `failedReason`, which can be long. Read one job to get the reason it failed.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CatalogJob"}}}}},"401":{"$ref":"#/components/responses/401ApplicationResponse"}}}}}}
```

## Create Catalog Job

> Queues a job and answers at once with its id. The job then runs detached. Read \`GET /limio/jobs/{id}\` to learn where it got to.\
> \
> Use a job for work that is too large for one request: import a file of offers, products or pages, edit or copy many items at once, export the catalog, or build a catalog in one step. Queue the job, do something else, and read the job later. To create or change one item, use \`POST /limio/catalogs/1/items/{path}\`, which answers when the work is done.\
> \
> \`jobType\` selects the work, and the rest of the body is the payload of that job type. \`updatePath\` is the catalog path that the job writes to, for the job types that write.\
> \
> A job runs with the permissions of the caller who queued it, so every record it touches answers to the same grants as a direct write would.

```json
{"openapi":"3.1.0","info":{"title":"Limio Commerce API","version":"1.0.0"},"tags":[{"name":"Catalog Jobs","description":"Queue work that is too large for one request, then read the job to learn where it got to. A job answers at once with an id and runs detached, so a caller queues it, does something else, and reads it later.\n\nUse a job to import a file of items, to edit or copy many items at once, to export the catalog or the order data, to build a catalog in one step, or to rebuild the search index. To create or change one item, use Catalog Management, which answers when the work is done.\n\nA job runs with the permissions of the caller who queued it. Reading a job takes the same permission as queueing it."}],"servers":[{"url":"https://{shard}.{domain}","variables":{"domain":{"default":"prod.limio.com"},"shard":{"default":"your-environment"}}}],"security":[{"bearerAuth":["catalog:write"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2.0 Bearer token for authenticated API access. Required for order submission, object management, and administrative operations.\n\nObtain a token via the OAuth flow described in [OAuth Bearer Token](https://docs.limio.com/developers/api-documentation/authentication-overview/oauth-bearer-token).\n\nPass the token in the `Authorization` header: `Bearer <token>`"}},"responses":{"401ApplicationResponse":{"description":"Unauthorized: the request lacks valid authentication credentials. Verify your Bearer token or API key is correct and has not expired.","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string","description":"The unique identifier of the request"},"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"paths":{"/limio/jobs":{"post":{"tags":["Catalog Jobs"],"operationId":"createCatalogJob","summary":"Create Catalog Job","description":"Queues a job and answers at once with its id. The job then runs detached. Read `GET /limio/jobs/{id}` to learn where it got to.\n\nUse a job for work that is too large for one request: import a file of offers, products or pages, edit or copy many items at once, export the catalog, or build a catalog in one step. Queue the job, do something else, and read the job later. To create or change one item, use `POST /limio/catalogs/1/items/{path}`, which answers when the work is done.\n\n`jobType` selects the work, and the rest of the body is the payload of that job type. `updatePath` is the catalog path that the job writes to, for the job types that write.\n\nA job runs with the permissions of the caller who queued it, so every record it touches answers to the same grants as a direct write would.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"jobType":{"type":"string","description":"The work to do. `importData` loads items from a file. `bulkEdit` changes an attribute on many items. `bulkCopy` copies many items. `duplicateData` copies one tree. `creation` creates one item. `export` and `exportCatalogTable` write the catalog to a file. `exportAnalytics` writes order data to a file. `zuoraCatalogSync` reads the product catalog from Zuora. `catalogCreation` builds a catalog in one step. `indexer` rebuilds the search index.","enum":["bulkCopy","bulkEdit","catalogCreation","creation","duplicateData","export","exportAnalytics","exportCatalogTable","importData","indexer","zuoraCatalogSync"]},"updatePath":{"type":"string","description":"The catalog path that the job writes to, for a job type that writes."}},"required":["jobType"]}}}},"responses":{"200":{"description":"The job is queued.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Read the job at `GET /limio/jobs/{id}` with this id."}}}}}},"400":{"description":"No worker handles this `jobType`."},"401":{"$ref":"#/components/responses/401ApplicationResponse"},"403":{"description":"You may not queue this job type. Some types need a feature to be enabled for you: `export` and `exportCatalogTable` need catalog export, `exportAnalytics` needs subscription analytics, `zuoraCatalogSync` needs catalog sync, `catalogCreation` needs one-click catalog, and `indexer` needs catalog publish.\n\nThe `commit` job type is refused to every caller. The platform queues it for itself."}}}}}}
```

## Get Catalog Job

> Returns one job, with how far it has run and what it produced. This is the read that follows \`POST /limio/jobs\`.\
> \
> \`state\` says whether to read again. \`waiting\` and \`delayed\` mean the job has not started, \`active\` means it is running, and \`completed\` and \`failed\` are final. Read again only while the state is not final.\
> \
> A failed job carries \`failedReason\`. A job that wrote a file names it in \`returnValue\`; ask for it at \`GET /limio/jobs/{id}/file/{filename}\`.

```json
{"openapi":"3.1.0","info":{"title":"Limio Commerce API","version":"1.0.0"},"tags":[{"name":"Catalog Jobs","description":"Queue work that is too large for one request, then read the job to learn where it got to. A job answers at once with an id and runs detached, so a caller queues it, does something else, and reads it later.\n\nUse a job to import a file of items, to edit or copy many items at once, to export the catalog or the order data, to build a catalog in one step, or to rebuild the search index. To create or change one item, use Catalog Management, which answers when the work is done.\n\nA job runs with the permissions of the caller who queued it. Reading a job takes the same permission as queueing it."}],"servers":[{"url":"https://{shard}.{domain}","variables":{"domain":{"default":"prod.limio.com"},"shard":{"default":"your-environment"}}}],"security":[{"bearerAuth":["catalog:write"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2.0 Bearer token for authenticated API access. Required for order submission, object management, and administrative operations.\n\nObtain a token via the OAuth flow described in [OAuth Bearer Token](https://docs.limio.com/developers/api-documentation/authentication-overview/oauth-bearer-token).\n\nPass the token in the `Authorization` header: `Bearer <token>`"}},"parameters":{"jobId":{"in":"path","required":true,"name":"id","description":"The id that `POST /limio/jobs` answered with.","schema":{"type":"string"}}},"schemas":{"CatalogJob":{"type":"object","description":"A job, in the shape that a read returns.","properties":{"id":{"type":"string","description":"The id that the queue answered with."},"name":{"type":"string","description":"The job type, as it was queued."},"state":{"type":"string","description":"Where the job is. `waiting` and `delayed` mean it has not started, `active` means it is running, and `completed` and `failed` are final. `unknown` means the record does not settle a state.","enum":["waiting","delayed","active","paused","stuck","completed","failed","unknown"]},"progress":{"type":"number","description":"How far the job has run, as a percentage, when the job type reports it. Reads of a single job carry it; the list does not."},"message":{"type":"object","description":"A sentence for a person, written when the job finishes.","properties":{"notificationType":{"type":"string"},"message":{"type":"string"}}},"returnValue":{"type":"object","additionalProperties":true,"description":"What the job produced. An export puts the name of its file here, which is the name to ask for at `GET /limio/jobs/{id}/file/{filename}`."},"failedReason":{"type":"string","description":"Why the job failed. Only a read of a single job carries it: the reason can be long, so the list leaves it out."},"username":{"type":"string","description":"Who queued the job."},"data":{"type":"object","additionalProperties":true,"description":"The body that queued the job."},"processedOn":{"type":"number","description":"When the job started, in milliseconds since the epoch."},"timestamp":{"type":"number","description":"When the job was queued, in milliseconds since the epoch."}}}},"responses":{"401ApplicationResponse":{"description":"Unauthorized: the request lacks valid authentication credentials. Verify your Bearer token or API key is correct and has not expired.","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string","description":"The unique identifier of the request"},"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"paths":{"/limio/jobs/{id}":{"get":{"tags":["Catalog Jobs"],"operationId":"getCatalogJob","summary":"Get Catalog Job","description":"Returns one job, with how far it has run and what it produced. This is the read that follows `POST /limio/jobs`.\n\n`state` says whether to read again. `waiting` and `delayed` mean the job has not started, `active` means it is running, and `completed` and `failed` are final. Read again only while the state is not final.\n\nA failed job carries `failedReason`. A job that wrote a file names it in `returnValue`; ask for it at `GET /limio/jobs/{id}/file/{filename}`.","parameters":[{"$ref":"#/components/parameters/jobId"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogJob"}}}},"401":{"$ref":"#/components/responses/401ApplicationResponse"},"403":{"description":"You may not read a job of this type. Reading a job takes the same permission as queueing it."}}}}}}
```

## Get Catalog Job File

> Downloads the file that a job produced. The answer is CSV, not JSON.\
> \
> If you do not know the name of the file, \`GET /limio/jobs/{id}\` names it in \`returnValue\`.

```json
{"openapi":"3.1.0","info":{"title":"Limio Commerce API","version":"1.0.0"},"tags":[{"name":"Catalog Jobs","description":"Queue work that is too large for one request, then read the job to learn where it got to. A job answers at once with an id and runs detached, so a caller queues it, does something else, and reads it later.\n\nUse a job to import a file of items, to edit or copy many items at once, to export the catalog or the order data, to build a catalog in one step, or to rebuild the search index. To create or change one item, use Catalog Management, which answers when the work is done.\n\nA job runs with the permissions of the caller who queued it. Reading a job takes the same permission as queueing it."}],"servers":[{"url":"https://{shard}.{domain}","variables":{"domain":{"default":"prod.limio.com"},"shard":{"default":"your-environment"}}}],"security":[{"bearerAuth":["catalog:write"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2.0 Bearer token for authenticated API access. Required for order submission, object management, and administrative operations.\n\nObtain a token via the OAuth flow described in [OAuth Bearer Token](https://docs.limio.com/developers/api-documentation/authentication-overview/oauth-bearer-token).\n\nPass the token in the `Authorization` header: `Bearer <token>`"}},"parameters":{"jobId":{"in":"path","required":true,"name":"id","description":"The id that `POST /limio/jobs` answered with.","schema":{"type":"string"}}},"responses":{"401ApplicationResponse":{"description":"Unauthorized: the request lacks valid authentication credentials. Verify your Bearer token or API key is correct and has not expired.","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string","description":"The unique identifier of the request"},"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"paths":{"/limio/jobs/{id}/file/{filename}":{"get":{"tags":["Catalog Jobs"],"operationId":"getCatalogJobFile","summary":"Get Catalog Job File","description":"Downloads the file that a job produced. The answer is CSV, not JSON.\n\nIf you do not know the name of the file, `GET /limio/jobs/{id}` names it in `returnValue`.","parameters":[{"$ref":"#/components/parameters/jobId"},{"name":"filename","in":"path","required":true,"description":"The name of the file, as `returnValue` of the job gives it.","schema":{"type":"string"}}],"responses":{"200":{"description":"The file.","content":{"text/csv":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/401ApplicationResponse"},"403":{"description":"You may not read a job of this type. Reading what a job produced takes the same permission as queueing it."}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.limio.com/api/catalog-api/catalog-jobs.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.