ScreenshotResult

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/irmu-com/json-schema/irmu-com-screenshot-result-schema.json",
  "title": "ScreenshotResult",
  "description": "What `/screenshot` answers. `screenshot` is null while a crawl is still\nrunning and when it finished without producing an image; `status` and\n`error` are what tell those two apart.\n\nStandalone rather than the crawl envelope, like `/chatgpt`'s: there is no\n`content` here, because a recipe that ends in a screenshot is never a\ndocument recipe and so never comes back as a page.\n",
  "x-generated": "2026-11-05",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/irmu-com-openapi.yaml#/components/schemas/ScreenshotResult",
  "type": "object",
  "required": [
    "url",
    "domain",
    "screenshot",
    "ai_query",
    "credits_charged",
    "credits_remaining",
    "job_id",
    "status",
    "data",
    "position",
    "error",
    "debug"
  ],
  "properties": {
    "url": {
      "type": "string",
      "format": "uri",
      "description": "The page that was photographed, as it was asked for."
    },
    "domain": {
      "type": "string",
      "description": "The host the crawl was tallied against for the day, lowercased.\n"
    },
    "screenshot": {
      "type": [
        "string",
        "null"
      ],
      "format": "byte",
      "description": "The picture: a full-page JPEG, base64 encoded, with no `data:` prefix.\nFull page means the entire scroll height rather than the viewport, so\na long page produces a tall image and a large field -- several\nmegabytes is ordinary, and base64 adds about a third on top.\n\nNull when there is no picture, which is either a crawl still running\nor one that produced none. `status` says which, and `error` says why.\n"
    },
    "ai_query": {
      "type": "string",
      "description": "The question that was asked, echoed back. Empty when none was. Here to\nexplain `data` rather than the bill: it costs nothing on this endpoint.\n"
    },
    "credits_charged": {
      "type": "integer",
      "description": "30 for a screenshot that was taken or is still being taken, 0 for one\nthat produced nothing -- those are refunded. Flat: none of the options\nmove it.\n"
    },
    "credits_remaining": {
      "type": "integer",
      "description": "The organization's balance afterwards."
    },
    "job_id": {
      "type": "string",
      "description": "What this ran under. Collect a `202` from `/crawl/{job}` with it.\n"
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "running",
        "done",
        "failed"
      ],
      "description": "`queued` and `running` mean paid for and not finished -- poll it.\n`done` and `failed` are final.\n"
    },
    "data": {
      "type": [
        "object",
        "null"
      ],
      "additionalProperties": true,
      "description": "Whatever else the crawl collected -- the answer to an `ai_query` when\none was asked, and the page's own url and title. Null when it\ncollected nothing.\n\nThe image is **not** in here. It is lifted into `screenshot` and\nremoved from this object rather than repeated, because sending several\nmegabytes twice is not a rounding error.\n"
    },
    "position": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Where it sits in the crawler's queue while `queued`."
    },
    "error": {
      "type": [
        "string",
        "null"
      ],
      "description": "Why no picture came back. Null otherwise."
    },
    "debug": {
      "description": "Where the crawl had got to, when the crawler stopped waiting and\nlooked. Only sent when the request carries `debuga=1` -- a screenshot\nand the page source run to a megabyte -- and null otherwise.\n\nThe picture in here is **not** the one you paid for. `screenshot`\nabove is the deliverable, a full-page image; this is a viewport\nthumbnail off the live tab, and it never stands in for the other. A\npending response carries this one and not that one.\n",
      "oneOf": [
        {
          "$ref": "#/$defs/CrawlSnapshot"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "$defs": {
    "CrawlSnapshot": {
      "type": "object",
      "description": "Where a crawl had got to, for one that is still running or failed. Only\nsent when the request carries `debuga=1`.\n\nThe crawler stops waiting long before it stops working, and when it stops\nwaiting it looks at the tab: the url the browser is on, a picture of what\nis on screen, and the page source as it stands. That is what this is --\na diagnosis for a request that timed out, not a result. Nothing is\ncharged for it.\n\nNull on anything that is not still running. A finished or failed crawl has\nno tab left to look at, and a crawl still in the queue has not opened one\nyet.\n\nTwo things to know when reading one. The image is the **viewport**, not\nthe whole page, so it is not the picture `/screenshot` sells -- it is a\nthumbnail at quality 60, meant to be looked at rather than kept. And\neither artefact may be missing: they are captured independently, because a\nnavigation can destroy one without touching the other, so half a snapshot\nis ordinary. The missing half reads as null rather than going absent.\n\nA blank image beside a near-empty `html` is not a broken capture -- it\nmeans the crawl stalled *inside* a navigation, with the old document\nalready replaced. That is itself the answer.\n",
      "required": [
        "url",
        "screenshot",
        "html"
      ],
      "properties": {
        "url": {
          "type": [
            "string",
            "null"
          ],
          "format": "uri",
          "description": "The url the tab was on, which a redirect may have moved away from the\none you asked for.\n"
        },
        "screenshot": {
          "type": [
            "string",
            "null"
          ],
          "format": "byte",
          "description": "A base64 JPEG of the viewport, with no `data:` prefix -- decode it as\nit stands. Null when the capture raced a navigation and lost.\n"
        },
        "html": {
          "type": [
            "string",
            "null"
          ],
          "description": "The page source at that moment, half-loaded and all. Null when the\ncapture raced a navigation and lost.\n"
        }
      }
    }
  }
}