> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skinai.co/llms.txt
> Use this file to discover all available pages before exploring further.

# get_skin_scan

> Poll a scan and read its scores.

Returns the scan's status without waiting. When `status` is `completed`, `result` carries the scores. Follow `next_action`, `retry_after_seconds` and `max_auto_checks`; the full contract is in [scan lifecycle](/scan-lifecycle#polling).

`progress` values are raw provider measurements. Don't rank them, convert them to percentages or compare different metrics. Keep `limitations` attached.

**Common errors:** `not_found` (a wrong token, an expired or deleted scan, or a scan that doesn't exist), `rate_limited`.

|             |                                                                     |
| ----------- | ------------------------------------------------------------------- |
| Tool        | `get_skin_scan`                                                     |
| Listed on   | `/mcp` (guest) and `/mcp/account` (OAuth)                           |
| Annotations | `readOnlyHint: true` `destructiveHint: false` `openWorldHint: true` |

## Input

Sent as `params.arguments` of `tools/call`. Unknown keys are rejected with `invalid_input`.

<ParamField body="run_id" type="string" required>
  Format `uuid`.
</ParamField>

<ParamField body="access_token" type="string" required>
  Pattern `^[a-f0-9]{64}$`.
</ParamField>

## Output

Returned as `structuredContent`, and as the same object serialised in `content[0].text`. On failure the result has `isError: true` and an [error body](/errors) instead.

<ResponseField name="next_action" type="enum<string>" required>
  One of `upload_photo`, `check_again`, `show_result`, `stop`.
</ResponseField>

<ResponseField name="retry_after_seconds" type="integer" required>
  Range 0–9007199254740991.
</ResponseField>

<ResponseField name="max_auto_checks" type="integer" required>
  Range 0–9007199254740991.
</ResponseField>

<ResponseField name="processing_deadline_at" type="number | null" required />

<ResponseField name="message" type="string" required />

<ResponseField name="instructions" type="string" required />

<ResponseField name="run_id" type="string" required>
  Format `uuid`.
</ResponseField>

<ResponseField name="status" type="enum<string>" required>
  One of `awaiting_upload`, `queued`, `processing`, `completed`, `failed`, `expired`, `deleted`.
</ResponseField>

<ResponseField name="expires_at" type="number" required />

<ResponseField name="result" type="object | null" required>
  <Expandable title="properties">
    <ResponseField name="scores" type="object[]" required>
      3–7 items.

      <Expandable title="item">
        <ResponseField name="title" type="enum<string>" required>
          One of `wrinkles`, `redness`, `pores`, `eye_bags`, `pigmentation`, `acne`, `sagging`.
        </ResponseField>

        <ResponseField name="progress" type="number" required>
          Range 0–100.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="explanation" type="string" required />

    <ResponseField name="next_steps" type="string[]" required />

    <ResponseField name="limitations" type="string" required />

    <ResponseField name="schema_version" type="1" required />
  </Expandable>
</ResponseField>

<ResponseField name="error_code" type="string | null" required />

<ResponseField name="save_url" type="string | null" required>
  Format `uri`.
</ResponseField>

<ResponseField name="save_instructions" type="string | null" required />

<AccordionGroup>
  <Accordion title="Description the model receives">
    ```text theme={null}
    Check a guest scan without waiting for analysis to finish. Follow next_action, retry_after_seconds, max_auto_checks and instructions. Never poll before upload or after a terminal result/error; never restart a scan to check its status. Other tools can run while the scan processes. This uses ordinary status polling, not MCP Tasks or push notifications. Scores are cosmetic observations, not a diagnosis.
    ```
  </Accordion>

  <Accordion title="Input JSON Schema">
    ```json theme={null}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "run_id": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "access_token": {
          "type": "string",
          "pattern": "^[a-f0-9]{64}$"
        }
      },
      "required": [
        "run_id",
        "access_token"
      ],
      "additionalProperties": false
    }
    ```
  </Accordion>

  <Accordion title="Output JSON Schema">
    ```json theme={null}
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "next_action": {
          "type": "string",
          "enum": [
            "upload_photo",
            "check_again",
            "show_result",
            "stop"
          ]
        },
        "retry_after_seconds": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "max_auto_checks": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "processing_deadline_at": {
          "type": [
            "number",
            "null"
          ]
        },
        "message": {
          "type": "string"
        },
        "instructions": {
          "type": "string"
        },
        "run_id": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "status": {
          "type": "string",
          "enum": [
            "awaiting_upload",
            "queued",
            "processing",
            "completed",
            "failed",
            "expired",
            "deleted"
          ]
        },
        "expires_at": {
          "type": "number"
        },
        "result": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "scores": {
                  "minItems": 3,
                  "maxItems": 7,
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "title": {
                        "type": "string",
                        "enum": [
                          "wrinkles",
                          "redness",
                          "pores",
                          "eye_bags",
                          "pigmentation",
                          "acne",
                          "sagging"
                        ]
                      },
                      "progress": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 100
                      }
                    },
                    "required": [
                      "title",
                      "progress"
                    ],
                    "additionalProperties": false
                  }
                },
                "explanation": {
                  "type": "string"
                },
                "next_steps": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "limitations": {
                  "type": "string"
                },
                "schema_version": {
                  "type": "number",
                  "const": 1
                }
              },
              "required": [
                "scores",
                "explanation",
                "next_steps",
                "limitations",
                "schema_version"
              ],
              "additionalProperties": false
            },
            {
              "type": "null"
            }
          ]
        },
        "error_code": {
          "type": [
            "string",
            "null"
          ]
        },
        "save_url": {
          "anyOf": [
            {
              "type": "string",
              "format": "uri"
            },
            {
              "type": "null"
            }
          ]
        },
        "save_instructions": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "next_action",
        "retry_after_seconds",
        "max_auto_checks",
        "processing_deadline_at",
        "message",
        "instructions",
        "run_id",
        "status",
        "expires_at",
        "result",
        "error_code",
        "save_url",
        "save_instructions"
      ],
      "additionalProperties": false
    }
    ```
  </Accordion>
</AccordionGroup>

<RequestExample>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0", "id": 2, "method": "tools/call",
    "params": {
      "name": "get_skin_scan",
      "arguments": { "run_id": "db56607f-edeb-47f3-bc5d-812d7af19adb", "access_token": "<access_token>" }
    }
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Response (completed, structuredContent) theme={null}
  {
    "run_id": "db56607f-edeb-47f3-bc5d-812d7af19adb",
    "status": "completed",
    "expires_at": 1790790705460,
    "next_action": "show_result",
    "retry_after_seconds": 0,
    "max_auto_checks": 0,
    "processing_deadline_at": 1790186505703,
    "message": "Your scan is ready.",
    "instructions": "Stop polling and explain the returned result and its limitations. Saving is optional.",
    "save_url": "https://skan-connectors-staging.skan.workers.dev/scan/db56607f-…#<capability>",
    "save_instructions": "Open save_url. If account saving is configured, sign in with Google or Apple, …",
    "result": {
      "scores": [
        { "title": "wrinkles", "progress": 88 },
        { "title": "redness", "progress": 40 },
        { "title": "pores", "progress": 92 },
        { "title": "eye_bags", "progress": 65 },
        { "title": "pigmentation", "progress": 85 },
        { "title": "acne", "progress": 81 },
        { "title": "sagging", "progress": 100 }
      ],
      "explanation": "These appearance scores describe this photo. …",
      "next_steps": ["Keep a consistent skincare routine and compare photos under similar lighting."],
      "limitations": "Cosmetic appearance analysis, not a medical diagnosis. Scores are raw 0–100 provider values, …",
      "schema_version": 1
    },
    "error_code": null
  }
  ```
</ResponseExample>