# List AI sign design jobs (`list_ai_sign_design_jobs`)

List the AI sign design jobs that integrations and AI agents started for this store, newest first, with an opaque cursor. Filter by status or product_family. Each row has the id, status, product family and credit charge; read one job with get_ai_sign_design_job for its files. Designs from the customer customiser and the merchant admin are not listed. Requires ai_sign_designs:read. Has no side effects.

- Source URL: https://www.signcustomiser.com/help/mcp/tools/list_ai_sign_design_jobs/
- Markdown URL: https://www.signcustomiser.com/help/mcp/tools/list_ai_sign_design_jobs.md
- MCP endpoint: https://mcp.signcustomiser.com
- Required scope: `ai_sign_designs:read`
- Behaviour: read

## Purpose

Find a job whose id was lost, or see which designs are still running.

## Annotations

| Hint | Value |
| --- | --- |
| readOnlyHint | true |
| destructiveHint | false |
| idempotentHint | true |
| openWorldHint | false |

## Prerequisites

- A merchant has connected this store and approved the ai_sign_designs:read scope.

## Arguments

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | no | How many jobs to return per page, between 1 and 100. Defaults to 20. |
| `cursor` | string | no | The opaque next_cursor value from the previous page, sent back with identical filters. |
| `filter` | object | no | Optional filters. An unknown filter is rejected, never ignored. |
| `filter.status` | string | no | Only jobs in this state: queued, processing, delivered or failed. Expected to grow. |
| `filter.product_family` | string | no | Only jobs of this product family: neon, channel_letter, metal_cut_out. Expected to grow. |

## Result

A page of job rows (id, status, product_family, customiser_id, charge, created_at, completed_at) and the pagination block. The files and findings of a job are in get_ai_sign_design_job.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `request_id` | string | yes |  |
| `store` | object | yes |  |
| `store.id` | integer | yes |  |
| `store.name` | string | yes |  |
| `jobs` | array of object | yes |  |
| `jobs[].id` | string | yes |  |
| `jobs[].status` | string | yes | One of: `queued`, `processing`, `delivered`, `failed`. |
| `jobs[].product_family` | string | yes | One of: `neon`, `channel_letter`, `metal_cut_out`. |
| `jobs[].customiser_id` | integer or null | no |  |
| `jobs[].charge` | object | yes |  |
| `jobs[].charge.state` | string | yes |  |
| `jobs[].charge.units` | integer | yes |  |
| `jobs[].created_at` | string | yes |  |
| `jobs[].completed_at` | string or null | no |  |
| `pagination` | object | yes |  |
| `pagination.has_more` | boolean | yes |  |
| `pagination.next_cursor` | string or null | no |  |

## Error cases

| Code | Recovery |
| --- | --- |
| `insufficient_scope` | The connection was approved without ai_sign_designs:read. |
| `invalid_cursor` | The cursor belongs to other filters. Call the tool again without a cursor. |
| `invalid_parameter` | A filter value is not supported; allowed_values lists the accepted values. |

## Example: List the jobs that are still running

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_ai_sign_design_jobs",
    "arguments": {
      "filter": {
        "status": "processing"
      }
    }
  }
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "jobs": [
        {
          "id": "aijob_4k8m2p6r0t3v7x1z5b9d3f7h2j",
          "status": "processing",
          "product_family": "neon",
          "customiser_id": null,
          "charge": {
            "state": "reserved",
            "units": 1
          },
          "created_at": "2026-10-20T09:31:00Z",
          "completed_at": null
        }
      ],
      "pagination": {
        "has_more": false,
        "next_cursor": null
      }
    }
  }
}
```

## Example: A status that does not exist (error)

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_ai_sign_design_jobs",
    "arguments": {
      "filter": {
        "status": "complete"
      }
    }
  }
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "invalid_parameter",
        "title": "Invalid parameter",
        "detail": "The filter[status] value is not a supported job status.",
        "recovery": "Correct the parameter named in parameter. Dates are YYYY-MM-DD in UTC and identifiers are integers between 1 and 2147483647.",
        "parameter": "filter[status]",
        "allowed_values": [
          "queued",
          "processing",
          "delivered",
          "failed"
        ]
      }
    }
  }
}
```