---
title: "Measure a set of screenshots against a category of the App Screenshot Index"
method: POST
path: "/screenshots/score"
tags: ["Screenshots"]
---

# Measure a set of screenshots against a category of the App Screenshot Index

`POST /screenshots/score`

## Request

- Base URL: `https://pagefully.com/api/v1`
- URL: `https://pagefully.com/api/v1/screenshots/score`
- Auth: HTTP bearer

Reads a set of screenshots with the reader the App Screenshot Index uses on the top 100 free apps of each category, and answers with the same tactic keys: each screenshot's words, colour and tactics, and each notable tactic with whether the set has it and what share of the category, of its top ten and of the rest do. The set is one of: `page_id` (a page made here: its drawn iPhone screenshots), `app_id` (an app on the workspace: the iPhone screenshots of its listing as Pagefully holds them, which works for an app that is not on the public store), or `app_store_url` or `app_store_id` (a public App Store app). No picture or address of a picture is taken. With `baseline`, a second set named the same way, the answer also has `changes`: the tactics gained, dropped and kept from the baseline to the set. The category is the app's own unless `category` names one of the Index's slugs. An unknown slug is 404 and nothing is read. Where the Index does not hold the app's own category the answer has the tags, `category` null and `category_note`. A screenshot is read once and kept. When every screenshot of the request has been read the answer is 200. When some have not, the answer is 202 with a `job_id`: poll GET /v1/jobs/{id} until it is done, then send the same request again. Reading is metered: 60 new screenshots a day for a workspace and 10 of one set, the same on every plan. Past the day's count the answer is 429 and nothing is read. A request that starts a read is also one of the token's 20 generation starts an hour. There is no score. The numbers say what leading apps do, not what causes installs.

## Request body

- object
  - `page_id` string, uuid: A page made here.
  - `app_id` string, uuid: An app on the workspace.
  - `app_store_url` string: A public App Store app, by its address.
  - `app_store_id` string: A public App Store app, by Apple's id.
  - `category` string: One of the Index's category slugs, such as health-fitness. The app's own when left out.
  - `baseline` object: The older set, to compare with: one of the same four fields.
    - `page_id` string, uuid
    - `app_id` string, uuid
    - `app_store_url` string
    - `app_store_id` string

## Response `200`

Every screenshot was read before: the set, scored.

- ScreenshotScore
  - `screenshots` object[], required
    - `screenshot` integer, required: Its place in the set, from 1.
    - `screenshots_in_set` integer, required
    - `image_url` string, nullable, required: The picture at display size.
    - `counted` boolean, required: One of the first six, which the comparison counts.
    - `headline` string, required
    - `subline` string, required
    - `kicker` string, required
    - `quote` string, required
    - `leads_with` string, required: What the words lead with: problem, feature, outcome, identity, trust, price, new or other.
    - `colour` object, required
      - `family` string, required
      - `hex` string, required
      - `lightness` number, required
    - `tactics` object[], required
      - `key` string, required
      - `label` string, required
      - `group` string, required
  - `story` string[], required: What each counted screenshot leads with, in order.
  - `set_tactics` object[], required: Facts about the whole set.
    - `key` string, required
    - `label` string, required
    - `group` string, required
  - `tactics` object[], required: Every tactic the set has, and every one it lacks that half the category, or the top ten more than the rest, has. Empty with no category.
    - `key` string, required
    - `label` string, required
    - `group` string, required
    - `group_label` string, required
    - `what_it_is` string, required
    - `category` string, nullable, required
    - `apps` integer, required
    - `apps_using` integer, required
    - `apps_share` number, required: A percentage of the category's apps.
    - `screenshots` integer, required
    - `screenshots_using` integer, required
    - `screenshots_share` number, required
    - `top_ten` object, required
      - `apps` integer, required
      - `using` integer, required
    - `rest` object, required
      - `apps` integer, required
      - `using` integer, required
    - `page_url` string, required
    - `in_set` boolean, required
    - `on_screenshots` integer[], required
    - `standing` 'shared' | 'rare' | 'yours' | 'missing' | 'not_yours', required: Where the tactic stands for this set.
  - `summary` object, nullable, required
    - `shared` string[], required
    - `rare` string[], required
    - `missing` string[], required
    - `top_ten_do_more` string[], required
  - `set` object, required
    - `kind` 'page' | 'app' | 'app_store', required
    - `page_id` string, uuid
    - `app_id` string, uuid
    - `app_store_id` string
    - `name` string, required
    - `app` string, required
    - `screenshots` integer, required
    - `left_out` integer, required
  - `category` object, nullable, required
    - `slug` string, required
    - `name` string, required
    - `apps` integer, required
    - `read_on` string, required
    - `url` string, required
    - `chosen` 'asked' | 'the_apps_own', required
  - `category_note` string, nullable, required: Why there is no comparison.
  - `baseline` object: The second set, scored the same way, when one was asked for.
  - `changes` object: From the baseline to the set: `gained`, `dropped` and `kept`, each a list of tactics with `before` and `after` (the screenshots that carried it) and the category's numbers; and `screenshots`, `story` and `colours` before and after.
  - `basis` object, required
    - `screenshots_counted` integer, required
    - `said` string, required
  - `reads` object, required
    - `a_day` integer, required
    - `left_today` integer, required
  - `note` string, required: What the numbers are and are not.

## Other responses

- `202`: Some screenshots are being read. Poll the job, then send the same request again.
- `400`: The request could not be read: a body that is not a JSON object, or a field missing or of the wrong kind.
- `401`: No token, or one that is not valid or has been revoked.
- `403`: The token's scope does not allow this call.
- `404`: Not found on this workspace.
- `409`: `not_ready`: the page has no drawn screenshots yet, or the app's listing has not been read.
- `422`: Understood, and refused by the product. The message says why, in a sentence that can be shown as it is.
- `429`: Too many calls: 120 requests a minute for a token, and 20 generation starts an hour. `retry_after` is seconds.

---

[API](https://skmtc.dev/pagefully/apis/pagefully-api.md) · [All operations](https://skmtc.dev/pagefully/apis/pagefully-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pagefully/apis/pagefully-api/revisions/60e17ce09d31?raw)