Add an endpoint for image usages by supplier

[junyuanxue]

What does this change?

• Adds an endpoint /usage/suppliers/:id/images, which returns a paginated list of images along with its relevant usages for each agency.

• We only care about usages that are under published, unknown, and removed statuses for now, on digital and print platforms.

• I've allowed for usage added date range to be passed in via search params to give us more flexibility around investigating various date ranges and compare against Kevin's RCS email, without being limited to the 'last 30 days' logic.

• This endpoint would be extremely useful for providing some transparency around image usages as we investigate usage reporting in the Grid and quota counting from RCS.

How should a reviewer test this change?

• Run the Grid locally with ./dev/script/start.sh --use-TEST
• Go to the endpoint with a generous date range so you get more results: https://api.media.local.dev-gutools.co.uk/usage/suppliers/getty/images?q=usages@%3Cadded:2026-07-31%20usages@%3Eadded:2016-07-01&length=100&offset=0
• You can page through the result by updating offset and length in the search params

{
  "offset": 0,
  "length": 73,
  "total": 73,
  "data": [
    {
      "id": "09f2c303a1b00697a092272156b4b149cb386354",
      "supplier": "Getty Images",
      "usages": [
        {
          "id": "front/34efed86f207c04264e9ee2ee2cb4bf4_d9a2c6f3b5c5d77d95dfdfd74b834ea3",
          "references": [
            {
              "type": "front",
              "name": "olly"
            }
          ],
          "platform": "digital",
          "media": "image",
          "status": "unknown",
          "dateAdded": "2023-04-27T14:29:21.150Z",
          "lastModified": "2023-04-27T14:29:21.150Z",
          "frontUsageMetadata": {
            "addedBy": "[email protected]",
            "front": "olly"
          }
        }
      ]
    },
    {
      "id": "0345c73bf81cafeb11ef8bc1ccc26ff2410a67f4",
      "supplier": "Getty Images",
      "usages": [
        {
          "id": "front/2b46ae683500c561863adfb0856324e_a3f8975262b7c4085f9d07aba3876f56",
          "references": [
            {
              "type": "front",
              "name": "uk"
            }
          ],
          "platform": "digital",
          "media": "image",
          "status": "unknown",
          "dateAdded": "2023-05-04T08:24:04.750Z",
          "lastModified": "2023-05-04T08:24:04.750Z",
          "frontUsageMetadata": {
            "addedBy": "[email protected]",
            "front": "uk"
          }
        }
      ]
    },
   // ...etc etc
  ]
}

Tested? Documented?

• locally by committer
• locally by Guardian reviewer
• on the Guardian's TEST environment
• relevant documentation added or amended (if needed)

---

• To see the specific tasks where the Asana app for GitHub is being used, see below:
  • https://app.asana.com/0/0/1217550364887307

[github-actions]

Deploy build 14985 of media-service::grid::all to TEST

All deployment options

• Deploy build 14985 of media-service::grid::all to TEST
• Deploy parts of build 14985 to TEST by previewing it first
• What's on TEST right now?

---

From guardian/actions-riff-raff.

[JustinPinner]

There is an upper bound to consider for elasticsearch pagination - beyond a certain limit performance drops off a cliff, so it might be good to sanitise the offset value unless that's taken care of elsewhere. See https://www.elastic.co/docs/reference/elasticsearch/rest-apis/paginate-search-results

[JustinPinner]

It might also be that you'll never get anywhere close to the limit in this context.

[junyuanxue]

Within the API endpoint I'm limiting length to the maxSize set in SearchParams which is 200. I could enforce this check within this function too

Edit: added :)

[junyuanxue]

Sorry I misunderstood your point entirely! That's a useful callout for sure. I've tweaked how search params are validated and included that.

We don't seem to have that guard on the images search though, unless I'm missing something? Curious how we'd handle that 👀

[JustinPinner]

I'm not really familiar with Grid enough myself yet. If there is already some paging going on, then it's likely to be fine.

I just know that in CAPI we have to have a hard limit on how deeply we can page and it's waaay less that 10K. The change you've made sets the default cap limit but in practice the cluster's actual performance may dictate a lower value.

I'd have to defer all this to anyone who's closer to the code for the final approval. This was the only thing that caught my eye.

[junyuanxue]

Ah I think there is a hardcoded 10k check from the FE 😂

[junyuanxue]

I think a cursor-based pagination would bypass this problem. But I don't really want to introduce a new pattern. As this behaves pretty similarly as offset-based paginated image search, keeping the 10k limit seems to be the simple safeguard. Realistically we have ~6000 unique images for the highest-usage supplier in a 30-day window which is what we're interested in (the rest are more around or under 1000)

[hk-15]

I have been playing around with this and as far as I can see it is all working as it should 🎉

[gu-prout]

Overdue on auth, usage, image-loader, metadata-editor, thrall, leases, cropper, collections, media-api, kahuna (merged by @junyuanxue 30 minutes and 3 seconds ago) What's gone wrong?

[gu-prout]

Seen on auth, usage, image-loader, metadata-editor, thrall, leases, cropper, collections, media-api, kahuna (merged by @junyuanxue 51 minutes and 1 second ago) Please check your changes!