GET /v1/files accepts updatedAfter and createdAfter filters, so each sync fetches only the files that changed since the last one. Use it to keep Snowflake, BigQuery or any other warehouse in step with your fileAI workspace without re-reading everything.

​
When to use it

  • Scheduled syncs to a warehouse or data lake: use this page.
  • Reacting to each upload as it finishes: use processing callbacks instead, and keep a periodic incremental sync as a safety net.
This is insert-and-update capture only. Deleted files never appear in GET /v1/files, so you cannot see deletions this way. See Deletions.

​
How it works

1

Store a watermark

After each successful sync, save the largest updatedAt you loaded. On the first run there is no watermark: fetch everything.
2

Fetch everything changed since the watermark

Call GET /v1/files?updatedAfter=<watermark>, sorted by updatedAt ascending, and page through every result.
3

Deduplicate and merge

The filter is inclusive, so the boundary file comes back again. Merge on fileId, keeping the row with the newest updatedAt.
4

Advance the watermark

Only after every page has loaded, save the new maximum updatedAt.

​
Filters

Both are inclusive: a file with updatedAt = 2025-01-01T12:00:00.000Z is returned for updatedAfter=2025-01-01T12:00:00.000Z. A value that is not a valid timestamp is rejected with 422. Send timestamps in UTC; createdAt and updatedAt come back in UTC with millisecond precision. You can combine the filters with fileIds and directoryId.

​
Choosing a pagination mode

GET /v1/files supports both pagination modes. Use cursor mode with sortBy=updatedAt&sortOrder=ASC: pages are keyed on the sort value and the file’s id, so a file written mid-walk does not shift rows you have not read yet. A file edited during your walk can still turn up again on the next sync; the inclusive filter plus deduplication covers this. If you must use legacy page/limit, always send both sortBy and sortOrder, or the order is unspecified. Pagination explains why.

​
What changes updatedAt

Any change to a file’s record moves its updatedAt, including:
  • metadata changes, status changes and reprocessing (including OCR)
  • extracted values and schema updates
  • classification, tag, contact or vendor changes
  • workflow step changes

​
Deletions

Deleted files are excluded from every GET /v1/files response, including filtered ones. To detect them, run a periodic full sync and remove rows from your warehouse that no longer come back.

​
Example

The first page of everything changed since the watermark:
Follow pagination.nextCursor until pagination.hasMore is false, then merge and advance the watermark. The warehouse sync recipe has the full loop in Python and Node, and a Snowflake MERGE.

​
Reference

​
File fields

Each file in data (cursor mode) or files (legacy mode) carries: Legacy mode also returns count (total matches) and currentPage. Cursor mode returns pagination instead.

​
Quick reference

Pagination

Cursor and legacy modes, limits and cursor rules.

Warehouse sync recipe

A complete sync job, end to end.

Processing callbacks

Get told when an upload finishes instead of polling.

Errors

What a 422 or 400 from this endpoint looks like.