---
title: "List documents"
method: GET
path: "/v1beta/documents"
tags: ["Documents"]
---

# List documents

`GET /v1beta/documents`

List documents with cursor-based pagination.

## Query parameters

- `page_token` string — Opaque pagination token from a previous response. Pass next_page_token or prev_page_token from a previous response to continue pagination. Empty or omitted for the first page.
- `page_size` integer — Maximum number of items to return per page (1-100). Default: 50.
- `created.after` string, date-time — A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`]( http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime() ) to obtain a formatter capable of generating timestamps in this format.
- `created.before` string, date-time — A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`]( http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime() ) to obtain a formatter capable of generating timestamps in this format.
- `created_by_id` string[] — Filter by creator ID(s) (user or bot). Returns documents matching ANY of the specified IDs. REST: ?created_by_id=user_01h2xcejqtf2nbrexx3vqjhp41 or ?created_by_id=user_xxx&created_by_id=bot_yyy
- `access_level` AccessLevel[] — Filter by access level(s). Returns documents matching ANY of the specified levels. REST: ?access_level=private or ?access_level=private&access_level=organization
- `processing_status` ProcessingStatus[] — Filter by processing status(es). Returns documents matching ANY of the specified statuses. REST: ?processing_status=ready or ?processing_status=processing&processing_status=ready
- `sort` string — Sort field and direction. Prefix with `-` for descending order. Allowed values: created_at, updated_at, name, last_viewed_at, last_shared_at. Default (omitted): created_at descending. REST: ?sort=last_viewed_at or ?sort=-name
- `query` string — Full-text search filter. Case-insensitive substring match on document name and description. REST: ?query=budget
- `ownership` DocumentOwnership[] — Ownership filter. Returns documents matching the specified ownership state. REST: ?ownership=owned or ?ownership=not_owned
- `trash_state` DocumentTrashState[] — Trash state filter. Returns documents matching the specified trash state. REST: ?trash_state=active or ?trash_state=trashed or ?trash_state=active&trash_state=trashed Default (omitted): active documents only.
- `organization_scope` boolean — Organization scope filter. When true, restrict to documents within the user's organization. REST: ?organization_scope=true
- `title_contains` string — Case-insensitive substring match on document title. REST: ?title_contains=quarterly
- `description_contains` string — Case-insensitive substring match on document description. Documents with no description set will not match this filter. REST: ?description_contains=financial
- `source_format` string[] — Filter by source format(s). Returns documents matching ANY of the specified formats. Allowed values: pdf, docx, xlsx, csv, markdown. REST: ?source_format=pdf or ?source_format=docx&source_format=xlsx

## Response `200`

Success

- ListDocumentsResponse — ListDocumentsResponse contains a page of documents.
  - `items` Document[] — List of documents.
    - `access_level` 'private' | 'organization' | 'public', required
    - `created_at` string, date-time, required — Timestamp when document was created.
    - `created_by` Subject, required — Subject is a lightweight reference to either a user or a bot. Used in embedded fields like created_by. For full details, call GetUser or GetBot with the subject's id. subject_type_matches_id_prefix // id prefix must match type (user_ for user, bot_ for bot)
      - `id` string, required — Unique ID. user_xxx for users, bot_xxx for bots.
      - `name` string, required — Display name of the user or bot.
      - `type` 'user' | 'bot', required
    - `current_version` VersionRef — VersionRef is a lightweight reference to a version.
      - `id` string, required — Version ID. Pattern: ver_[0-9a-hjkmnp-tv-z]{26}
    - `description` string, nullable — Optional document description.
    - `general_access` 'private' | 'organization' | 'public'
    - `id` string, required — Unique ID for the document. Pattern: doc_[0-9a-hjkmnp-tv-z]{26}
    - `is_demo` boolean — Whether this document is a demo document created during FTUE onboarding.
    - `last_viewed_at` string, date-time — Timestamp when the authenticated user last viewed this document. Absent if the user has never viewed it.
    - `owner_organization_id` string — Organization that owns this document (via the document creator). Empty if the owner's organization could not be resolved.
    - `permission_set` DocumentPermissionSet — DocumentPermissionSet contains the permissions the authenticated user has on a document.
      - `attach_policy` boolean
      - `comment_private` boolean
      - `comment_public` boolean
      - `copy_content` boolean
      - `create_version` boolean
      - `export` boolean
      - `grant_access` boolean
      - `list_versions` boolean
      - `manage_access` boolean
      - `open` boolean
      - `screenshot` boolean
      - `trash` boolean
      - `view` boolean
      - `view_analytics` boolean
      - `view_leads` boolean
      - `view_timeline` boolean
    - `processing_status` 'processing' | 'ready' | 'failed', required
    - `shared_at` string, date-time — Timestamp when this document was last shared to the authenticated user. Absent if the document was never shared to them.
    - `source_format` string — Original file format of the document's current version (e.g., "pdf", "docx", "xlsx", "csv", "markdown"). Output-only field — not validated on input. Values are always one of the canonical format names written by the upload layer; arbitrary strings will not appear here.
    - `thumbnail_url` string — URL of the document thumbnail image.
    - `title` string, required — Document title.
    - `trashed_at` string, date-time — Timestamp when the document was trashed, if applicable. Absent if the document is not trashed.
    - `updated_at` string, date-time — Timestamp when document was last updated.
    - `url` string, uri, required — URL for accessing the document on Factify.
  - `pagination` Pagination, required — Pagination contains cursor-based pagination metadata. Follows Google AIP-158 for pagination field naming.
    - `has_more` boolean — Whether there are more results in the forward direction.
    - `next_page_token` string — Token to retrieve the next page of results. Empty if there are no more results in the forward direction.
    - `prev_page_token` string — Token to retrieve the previous page of results. Empty if this is the first page.

## Other responses

- `400` — Invalid request parameters
- `401` — Authentication failed - missing or invalid API key
- `403` — Authorization failed - valid key but insufficient permissions
- `404` — Resource not found
- `429` — Too many requests
- `500` — Internal server error

---

[API](https://skmtc.net/factify-inc/apis/factify-api.md) · [All operations](https://skmtc.net/factify-inc/apis/factify-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/factify-inc/factify-api/revisions/8baabdfb82bf/schema)