Compare two dataset versions

Request

List the episodes added, removed, or changed between two dataset versions. The version query parameter identifies the base dataset version; the path identifies the target dataset version.

added: The episode is in the target but not the base.
removed: The episode is in the base but not the target.
changed: The same episode is in both, but the dataset versions use different episode versions.

For a changed episode, the returned details come from the episode version used by the target. previousVersion is the episode version number used by the base.

Changes are ordered by episode start time and returned a page at a time; the response's counts cover the whole changeset. Pages are cursor-based: pass the previous page's nextCursor back as cursor to continue. Cursors are tied to the dataset, compared versions, and accessible project scope; restart the query if a cursor is rejected. A limit of 0 returns no changes or continuation cursor, while the counts still cover the whole changeset.

Security

ApiKey(Required scopes: datasets.list)

Path

idstringrequired

Dataset ID

versionNumberstring^[0-9]+$required

Target version number

Query

versioninteger, >= 1required

The base version to compare against.

limitnumber, [ 0 .. 2000 ]

Maximum number of items to return

Default:2000

cursorstring

Opaque cursor from the fg-pagination-next-cursor or, where supported, fg-pagination-previous-cursor response header.

includeArray of strings

Comma-separated list of optional related data to include on each episode.

Items Enum:"recordings""creationContext""properties"

Payload

// No request payload

Responses

A page of the changeset between the two versions

Headers

fg-pagination-next-cursorstring

Opaque cursor to supply as cursor on the next request when more results are available.

Bodyapplication/json

changesArray of objects(DatasetEpisodeChangeResponse)required

The requested page of changes, ordered by episode start time.

addedCountinteger, >= 0required

Total episodes present in the target version but not the base version.

removedCountinteger, >= 0required

Total episodes present in the base version but not the target version.

changedCountinteger, >= 0required

Total episodes present in both dataset versions but using different episode versions.

nextCursorstring or nullrequired

Pass this value as cursor to retrieve the next page. null on the last page.

Response

{
  "changes": [
    { … }
  ],
  "addedCount": 0,
  "removedCount": 0,
  "changedCount": 0,
  "nextCursor": "string"
}