feat(API): Remove offset query param from list workflow history endpoint

[SamWooler]

Summary

Removes the offset query parameter from GET /workflows/{workflowId}/history, leaving cursor-only pagination — matching every other Public API list endpoint.

This endpoint was only recently added, has low usage, and is being accepted as a breaking change without a deprecation window.

Also updates the public-api agent skill so future list endpoints pick limit off publicApiPaginationSchema instead of spreading it, which is what let offset leak onto this endpoint in the first place.

Demo:
https://www.loom.com/share/2cc0e4fd6c1c4e8db1cc9052abf6d1a3

How to test

• GET /api/v1/workflows/{workflowId}/history?limit=2 then page with the returned nextCursor — unchanged.
• GET /api/v1/workflows/{workflowId}/history?offset=2 — offset is now a no-op so this is a behaviour change to be aware of but not an error response.

Related Linear tickets, Github issues, and Community forum posts

https://linear.app/n8n/issue/API-185

Review / Merge checklist

• I have seen this code, I have run this code, and I take responsibility for this code.
• PR title and summary are descriptive.
• Docs updated or follow-up ticket created.
• Tests included.
• PR Labeled with Backport to Beta, Backport to Stable, or Backport to v1 (if the PR is an urgent fix that needs to be backported)

[n8n-assistant]

PR review overview

Based on ownership of the 5 changed files in this PR:

Ownership	Files owned	Share	Source code	Test files	Misc
@n8n-io/catalysts	4	80%	+22 / -8	+0 / -20	+0 / -0
@n8n-io/ligo	1	20%	+0 / -1	+0 / -0	+0 / -0
Total	5	100%	+22 / -9	+0 / -20	+0 / -0

[codecov]

Bundle Report

Bundle size has no change ✅

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[cubic-dev-ai]

No issues found across 5 files

Architecture diagram

sequenceDiagram
    participant Client
    participant API as Public API Handler
    participant DTO as ListWorkflowHistoryQueryDto
    participant Pager as Pagination Service
    participant DB as Database

    Note over Client,DB: Runtime flow for GET /workflows/{id}/history

    Client->>API: GET request with ?limit & ?cursor & ?offset
    
    API->>DTO: Validate query parameters
    Note over DTO: CHANGED: Picks 'limit' from schema.<br/>'offset' is no longer defined.
    
    alt Request contains 'offset'
        DTO-->>API: Silently strips 'offset' (inert)
    else Request contains 'cursor'
        DTO-->>API: Returns limit and encoded cursor
    end

    API->>Pager: decodeCursor(cursor)
    Note over Pager: Internal implementation still<br/>uses { offset, limit }
    Pager-->>API: Return internal offset/limit

    API->>DB: Query workflow history
    DB-->>API: Return records (data)

    API->>Pager: encodeNextCursor(nextOffset)
    Pager-->>API: Opaque string (e.g. "Y3Vyc29y...")

    API-->>Client: 200 OK { data, nextCursor }

    Note over Client,Pager: Skill Update: Future list endpoints must<br/>only pick 'limit' from publicApiPaginationSchema.

Loading

_{Re-trigger cubic}

[konstantintieber]

Well put 👍

[konstantintieber]

To add why we're accepting this breaking change on the otherwise "backwards compatible" public API:
This endpoint was released one month ago in July 28th on version 2.33.0 (see #34656)

Our telemetry shows that there are only a handful of customers using it. This data doesn't go as granular as to be able to tell whether the offset parameter is used in any of those usages.
Yet, since this is the only endpoint in the public API that exposes an offset parameter, we decided to accept this breaking change for an endpoint that has only been live for one month, to help us maintain a consistent public API experience.

[n8n-assistant]

Successfully created backport PR for release-candidate/2.36.x:

• feat(API): Remove offset query param from list workflow history endpoint (backport to release-candidate/2.36.x) #36952

[n8n-assistant]

Successfully created backport PR for release-candidate/2.35.x:

• feat(API): Remove offset query param from list workflow history endpoint (backport to release-candidate/2.35.x) #36953