# Get upload (`get_upload`)

Reads the state of one staged upload: whether the bytes have arrived, whether they passed verification, whether the object has been attached to a slot, and when the staging target expires. It is the call to poll between creating an upload and attaching it, and the place to look when an attach fails with an upload error. The presigned target is never returned here. It requires the customisers:read scope and has no side effects.

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

## Purpose

Check whether a staged upload is ready to attach, or why it was rejected.

## Annotations

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

## Prerequisites

- An upload id from create_upload.
- A merchant has connected this store and approved the customisers:read scope.

## Arguments

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `upload_id` | string | yes | The upload id create_upload returned. |

## Result

One upload record. The presigned target and its headers are deliberately omitted; they are returned only once, by create_upload.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `request_id` | string | yes |  |
| `store` | object | yes |  |
| `store.id` | integer | yes |  |
| `store.name` | string | yes |  |
| `upload_id` | string | yes |  |
| `status` | string | yes | Where the upload is in its lifecycle. Expected to grow: tolerate unknown values. One of: `pending`, `uploaded`, `attached`, `rejected`, `expired`. |
| `purpose` | string | yes | What the upload was declared for, which fixes its allowed content types and maximum size. Expected to grow. One of: `font_ttf`, `option_image`, `option_texture_image`, `backboard_shape_svg`, `label_image`. |
| `filename` | string or null | no |  |
| `content_type` | string or null | no |  |
| `byte_size` | integer or null | no |  |
| `verification_failure_code` | string or null | no | Why verification rejected the object, or null when it has not been rejected. |
| `expires_at` | string or null | no |  |
| `attached_at` | string or null | no |  |
| `created_at` | string or null | no |  |

## Error cases

| Code | Recovery |
| --- | --- |
| `insufficient_scope` | The connection was approved without customisers:read. |
| `resource_not_found` | No upload with that id belongs to this store, or it was pruned after expiring. Start again at create_upload. |

## Example: Poll an upload that has arrived

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_upload",
    "arguments": {
      "upload_id": "upl_9f2c4b7ad13e6058ba41cd"
    }
  }
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "upload_id": "upl_9f2c4b7ad13e6058ba41cd",
      "status": "uploaded",
      "purpose": "font_ttf",
      "filename": "Signature.ttf",
      "content_type": "font/ttf",
      "byte_size": 184320,
      "verification_failure_code": null,
      "expires_at": "2026-07-23T00:00:00Z",
      "attached_at": null,
      "created_at": "2026-07-22T00:00:00Z"
    }
  }
}
```

## Example: An upload id that has already been pruned (error)

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_upload",
    "arguments": {
      "upload_id": "upl_000000000000000000000"
    }
  }
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "resource_not_found",
        "title": "Resource not found",
        "detail": "The requested resource does not exist or does not belong to the authenticated store.",
        "recovery": "The identifier does not exist in this store. Use the matching list tool to rediscover a valid id."
      }
    }
  }
}
```