Items

Endpoint shortcuts

Use an access token for these calls. Replace the sample IDs with your own. Each endpoint page includes request and response examples.

The request examples use a Person collection with firstName and lastName properties. Use your collection's itemsType and property keys in your own requests.

The Item object

Use the collection's itemsType as the item's @type. For example, a Contact collection stores items with "@type": "Contact". Its properties define the other fields you can send.

json

{
  "@context": {...},
  "@id": "ChTOSFASLKdVOraA",
  "createdAt": "2021-01-08T10:24:26.612030+00:00",
  "updatedAt": "2021-02-15T15:48:18.007428+00:00",
  "@type": "{{itemType}}",
  ...
}

Properties

Property	Type	Description
@context	object	Optional JSON-LD context information.
@id	string	Unique object ID.
@type	string	Value comes from collection `itemsType` property
createdAt	string	Creation time as an ISO 8601 timestamp.
updatedAt	string	Last update time as an ISO 8601 timestamp.

Example

If your collection has properties with the keys firstName and lastName, an item looks like this:

json

{
  "@context": {...},
  "@id": "ChTOSFASLKdVOraA",
  "createdAt": "2021-01-08T10:24:26.612030+00:00",
  "updatedAt": "2021-02-15T15:48:18.007428+00:00",
  "@type": "Person",
  "firstName": "John",
  "lastName": "Malkovich",
}

Create an item

Create an item →

Retrieve an item

Get an item →

Update an item

Partial

Update an item →

Full update

Replace an item →

List all items

List items →

Filtering

Use filter to return matching items. Build a list of conditions, encode the whole list as compact JSON, and send that string as the query parameter. Even one condition needs a list, such as [{"name":"country","op":"eq","val":"US"}].

Each condition has three fields:

Field	Meaning
`name`	The API property key to filter, such as `country` or `createdAt`. Use the key returned by the API, not the property's display label.
`op`	A supported operator from the table below. Operator names are case-sensitive.
`val`	The comparison value: a string, number, boolean, list, or `null`, depending on the operator.

Multiple conditions are combined with AND: every condition must match. Use in for alternative values of one field. There is no general OR expression for conditions on different fields.

The request cards show the encoding step in each language:

Python: json.dumps(filters, separators=(",", ":"))
JavaScript: JSON.stringify(filters)
PHP: json_encode($filters, JSON_THROW_ON_ERROR)
Go: json.Marshal(filters)

Do not add indentation or formatting newlines. Pass the JSON string to your HTTP library's query parameters; it handles URL encoding. In Python, pass params to requests.get without URL-encoding the JSON yourself.

These examples use standard JSON values. The Datablist Python wrapper uses its JsonEncoder when values include native dates or decimals.

The examples below list collection items. Replace WORKSPACE_ID and COLLECTION_ID with your identifiers, provide your Bearer access token, and use property keys and values that exist in your collection. Choose a language in each request card. In cURL examples, replace ACCESS_TOKEN; --get makes a GET request and --data-urlencode safely encodes the JSON query parameter.

Supported operators

Operator	Matches	Value
`eq`	A field equal to a value.	String, number, or boolean.
`ne`	A field different from a value.	String, number, or boolean; use `isNotEmpty` to exclude empty values.
`array_contains`	An array containing one value.	One string, number, or boolean.
`in`	A field equal to any listed value.	A list of up to 200 strings, numbers, or booleans.
`not-in`	A field different from every listed value.	A list of up to 10 strings, numbers, or booleans.
`gt`	A field greater than a value.	A number or comparable string; a date for built-in timestamp fields.
`ge`	A field greater than or equal to a value.	Same as `gt`.
`lt`	A field less than a value.	Same as `gt`.
`le`	A field less than or equal to a value.	Same as `gt`.
`isNotEmpty`	An existing field whose value is neither an empty string nor `null`.	`null`.
`startsWith`	A string beginning with a prefix, respecting case.	A string prefix.
`gtRelative`	A timestamp later than a relative cutoff.	A relative-date string, such as `last-7-days`.
`ltRelative`	A timestamp earlier than a relative cutoff.	A relative-date string, such as `next-1-months`.
`withError`	A Run Status property with an error status.	`null`; the comparison value is determined by the operator.
`successful`	A Run Status property with a successful status.	`null`; the comparison value is determined by the operator.

Use JSON types that match your data: 50 is a number, true is a boolean, and "50" is a string. Use null without quotes where indicated. Custom property keys used in filters must be alphanumeric; built-in @id and @saveId are also accepted. Filtering is not available on @type or arbitrary nested object paths.

Equality

eq — equal to a value. This call returns items whose country is US.

Request

import json
import requests

url = "https://api.datablist.com/v1/data/WORKSPACE_ID/collections/COLLECTION_ID/items"

headers = {
    "Accept": "application/json",
    "Authorization": "Bearer <token>"
}

filters = [{
    "name": "country",
    "op": "eq",
    "val": "US"
}]

params = {}
params["filter"] = json.dumps(filters, separators=(",", ":"))

response = requests.get(url, headers=headers, params=params)

print(response.text)

ne — different from a value. This call excludes items whose country is US. Missing fields are not matches.

Request

import json
import requests

url = "https://api.datablist.com/v1/data/WORKSPACE_ID/collections/COLLECTION_ID/items"

headers = {
    "Accept": "application/json",
    "Authorization": "Bearer <token>"
}

filters = [{
    "name": "country",
    "op": "ne",
    "val": "US"
}]

params = {}
params["filter"] = json.dumps(filters, separators=(",", ":"))

response = requests.get(url, headers=headers, params=params)

print(response.text)

Arrays and lists

array_contains — one value in an array. This call returns items whose tags array contains customer.

Request

import json
import requests

url = "https://api.datablist.com/v1/data/WORKSPACE_ID/collections/COLLECTION_ID/items"

headers = {
    "Accept": "application/json",
    "Authorization": "Bearer <token>"
}

filters = [{
    "name": "tags",
    "op": "array_contains",
    "val": "customer"
}]

params = {}
params["filter"] = json.dumps(filters, separators=(",", ":"))

response = requests.get(url, headers=headers, params=params)

print(response.text)

in — any value in a list. This call returns items whose country is US or CA. It compares the field itself; use array_contains to search inside an array.

Request

import json
import requests

url = "https://api.datablist.com/v1/data/WORKSPACE_ID/collections/COLLECTION_ID/items"

headers = {
    "Accept": "application/json",
    "Authorization": "Bearer <token>"
}

filters = [{
    "name": "country",
    "op": "in",
    "val": ["US", "CA"]
}]

params = {}
params["filter"] = json.dumps(filters, separators=(",", ":"))

response = requests.get(url, headers=headers, params=params)

print(response.text)

not-in — none of the listed values. This call excludes items whose country is US or CA. Do not use a list containing null; missing fields are not matches.

Request

import json
import requests

url = "https://api.datablist.com/v1/data/WORKSPACE_ID/collections/COLLECTION_ID/items"

headers = {
    "Accept": "application/json",
    "Authorization": "Bearer <token>"
}

filters = [{
    "name": "country",
    "op": "not-in",
    "val": ["US", "CA"]
}]

params = {}
params["filter"] = json.dumps(filters, separators=(",", ":"))

response = requests.get(url, headers=headers, params=params)

print(response.text)

Ranges

gt — greater than. This call returns items with a score above 50.

Request

import json
import requests

url = "https://api.datablist.com/v1/data/WORKSPACE_ID/collections/COLLECTION_ID/items"

headers = {
    "Accept": "application/json",
    "Authorization": "Bearer <token>"
}

filters = [{
    "name": "score",
    "op": "gt",
    "val": 50
}]

params = {}
params["filter"] = json.dumps(filters, separators=(",", ":"))

response = requests.get(url, headers=headers, params=params)

print(response.text)

ge — greater than or equal to. This call includes a score of 50.

Request

import json
import requests

url = "https://api.datablist.com/v1/data/WORKSPACE_ID/collections/COLLECTION_ID/items"

headers = {
    "Accept": "application/json",
    "Authorization": "Bearer <token>"
}

filters = [{
    "name": "score",
    "op": "ge",
    "val": 50
}]

params = {}
params["filter"] = json.dumps(filters, separators=(",", ":"))

response = requests.get(url, headers=headers, params=params)

print(response.text)

lt — less than. This call returns items with a score below 80.

Request

import json
import requests

url = "https://api.datablist.com/v1/data/WORKSPACE_ID/collections/COLLECTION_ID/items"

headers = {
    "Accept": "application/json",
    "Authorization": "Bearer <token>"
}

filters = [{
    "name": "score",
    "op": "lt",
    "val": 80
}]

params = {}
params["filter"] = json.dumps(filters, separators=(",", ":"))

response = requests.get(url, headers=headers, params=params)

print(response.text)

le — less than or equal to. This call includes a score of 80.

Request

import json
import requests

url = "https://api.datablist.com/v1/data/WORKSPACE_ID/collections/COLLECTION_ID/items"

headers = {
    "Accept": "application/json",
    "Authorization": "Bearer <token>"
}

filters = [{
    "name": "score",
    "op": "le",
    "val": 80
}]

params = {}
params["filter"] = json.dumps(filters, separators=(",", ":"))

response = requests.get(url, headers=headers, params=params)

print(response.text)

Text and empty values

isNotEmpty — exclude empty strings and null values. This call returns items with a populated email field. Missing fields do not match. Whitespace-only strings are not trimmed, and this operator is not an empty-array or empty-object check.

Request

import json
import requests

url = "https://api.datablist.com/v1/data/WORKSPACE_ID/collections/COLLECTION_ID/items"

headers = {
    "Accept": "application/json",
    "Authorization": "Bearer <token>"
}

filters = [{
    "name": "email",
    "op": "isNotEmpty",
    "val": None
}]

params = {}
params["filter"] = json.dumps(filters, separators=(",", ":"))

response = requests.get(url, headers=headers, params=params)

print(response.text)

startsWith — a case-sensitive prefix. This call matches Datablist in companyName, but not datablist. It is a prefix range comparison, not substring, regular-expression, or full-text search.

Request

import json
import requests

url = "https://api.datablist.com/v1/data/WORKSPACE_ID/collections/COLLECTION_ID/items"

headers = {
    "Accept": "application/json",
    "Authorization": "Bearer <token>"
}

filters = [{
    "name": "companyName",
    "op": "startsWith",
    "val": "Data"
}]

params = {}
params["filter"] = json.dumps(filters, separators=(",", ":"))

response = requests.get(url, headers=headers, params=params)

print(response.text)

Dates

For built-in createdAt, updatedAt, and deletedAt fields, ordinary range operators accept ISO 8601 timestamps or Unix timestamps in seconds. This call returns items created on or after October 1, 2026 (UTC).

Request

import json
import requests

url = "https://api.datablist.com/v1/data/WORKSPACE_ID/collections/COLLECTION_ID/items"

headers = {
    "Accept": "application/json",
    "Authorization": "Bearer <token>"
}

filters = [{
    "name": "createdAt",
    "op": "ge",
    "val": "2026-10-01T00:00:00Z"
}]

params = {}
params["filter"] = json.dumps(filters, separators=(",", ":"))

response = requests.get(url, headers=headers, params=params)

print(response.text)

gtRelative — later than a relative cutoff. This call returns items updated within the last seven days. The comparison is strictly greater than the cutoff.

Request

import json
import requests

url = "https://api.datablist.com/v1/data/WORKSPACE_ID/collections/COLLECTION_ID/items"

headers = {
    "Accept": "application/json",
    "Authorization": "Bearer <token>"
}

filters = [{
    "name": "updatedAt",
    "op": "gtRelative",
    "val": "last-7-days"
}]

params = {}
params["filter"] = json.dumps(filters, separators=(",", ":"))

response = requests.get(url, headers=headers, params=params)

print(response.text)

ltRelative — earlier than a relative cutoff. This call returns items created before the cutoff one month from now. The comparison is strictly less than the cutoff.

Request

import json
import requests

url = "https://api.datablist.com/v1/data/WORKSPACE_ID/collections/COLLECTION_ID/items"

headers = {
    "Accept": "application/json",
    "Authorization": "Bearer <token>"
}

filters = [{
    "name": "createdAt",
    "op": "ltRelative",
    "val": "next-1-months"
}]

params = {}
params["filter"] = json.dumps(filters, separators=(",", ":"))

response = requests.get(url, headers=headers, params=params)

print(response.text)

Relative-date strings have the exact format last-N-unit or next-N-unit, where N is a non-negative integer and unit is minutes, hours, days, months, or years (always plural). Values are case-sensitive. Cutoffs are calculated from the server's current UTC time when the request is processed; months and years use calendar offsets. Use the built-in timestamp fields for these examples; a date-looking string in a custom text field is not automatically converted to a timestamp.

Run Status

These operators apply to a Run Status property, not an asynchronous task's lifecycle status. Replace runStatus with your property key.

withError — an error status.

Request

import json
import requests

url = "https://api.datablist.com/v1/data/WORKSPACE_ID/collections/COLLECTION_ID/items"

headers = {
    "Accept": "application/json",
    "Authorization": "Bearer <token>"
}

filters = [{
    "name": "runStatus",
    "op": "withError",
    "val": None
}]

params = {}
params["filter"] = json.dumps(filters, separators=(",", ":"))

response = requests.get(url, headers=headers, params=params)

print(response.text)

successful — a successful status.

Request

import json
import requests

url = "https://api.datablist.com/v1/data/WORKSPACE_ID/collections/COLLECTION_ID/items"

headers = {
    "Accept": "application/json",
    "Authorization": "Bearer <token>"
}

filters = [{
    "name": "runStatus",
    "op": "successful",
    "val": None
}]

params = {}
params["filter"] = json.dumps(filters, separators=(",", ":"))

response = requests.get(url, headers=headers, params=params)

print(response.text)

Deprecated aliases

Existing integrations can still use neq for ne and not_in for not-in. Use the canonical names in new calls.

neq — deprecated alias of ne.

Request

import json
import requests

url = "https://api.datablist.com/v1/data/WORKSPACE_ID/collections/COLLECTION_ID/items"

headers = {
    "Accept": "application/json",
    "Authorization": "Bearer <token>"
}

filters = [{
    "name": "country",
    "op": "neq",
    "val": "US"
}]

params = {}
params["filter"] = json.dumps(filters, separators=(",", ":"))

response = requests.get(url, headers=headers, params=params)

print(response.text)

not_in — deprecated alias of not-in.

Request

import json
import requests

url = "https://api.datablist.com/v1/data/WORKSPACE_ID/collections/COLLECTION_ID/items"

headers = {
    "Accept": "application/json",
    "Authorization": "Bearer <token>"
}

filters = [{
    "name": "country",
    "op": "not_in",
    "val": ["US", "CA"]
}]

params = {}
params["filter"] = json.dumps(filters, separators=(",", ":"))

response = requests.get(url, headers=headers, params=params)

print(response.text)

Filter by item ID

Use @id with eq for one item or in for a list of up to 200 item IDs. Use the item's identifier, not its full URL. An @id filter must be the only condition; other operators and combinations with property filters are not supported. These are direct ID lookups: order_by, count, and cursors do not provide sorted or paginated ID lookup results. For a single item, you can also use Get an item.

Request

import json
import requests

url = "https://api.datablist.com/v1/data/WORKSPACE_ID/collections/COLLECTION_ID/items"

headers = {
    "Accept": "application/json",
    "Authorization": "Bearer <token>"
}

filters = [{
    "name": "@id",
    "op": "eq",
    "val": "ITEM_ID"
}]

params = {}
params["filter"] = json.dumps(filters, separators=(",", ":"))

response = requests.get(url, headers=headers, params=params)

print(response.text)

Look up several item IDs:

Request

import json
import requests

url = "https://api.datablist.com/v1/data/WORKSPACE_ID/collections/COLLECTION_ID/items"

headers = {
    "Accept": "application/json",
    "Authorization": "Bearer <token>"
}

filters = [{
    "name": "@id",
    "op": "in",
    "val": ["ITEM_ID_1", "ITEM_ID_2"]
}]

params = {}
params["filter"] = json.dumps(filters, separators=(",", ":"))

response = requests.get(url, headers=headers, params=params)

print(response.text)

Combine filters

For example, return items in the US with a score from 50 through 80, inclusive:

Request

import json
import requests

url = "https://api.datablist.com/v1/data/WORKSPACE_ID/collections/COLLECTION_ID/items"

headers = {
    "Accept": "application/json",
    "Authorization": "Bearer <token>"
}

filters = [{
    "name": "country",
    "op": "eq",
    "val": "US"
}, {
    "name": "score",
    "op": "ge",
    "val": 50
}, {
    "name": "score",
    "op": "le",
    "val": 80
}]

params = {}
params["filter"] = json.dumps(filters, separators=(",", ":"))

response = requests.get(url, headers=headers, params=params)

print(response.text)

Query limits and performance

A request supports at most four conditions after operator expansion. startsWith and isNotEmpty each count as two conditions. For example, a prefix filter plus two ordinary filters fits the limit; a prefix filter plus three ordinary filters does not.
in accepts at most 200 values and not-in accepts at most 10 values. List values must be strings, numbers, or booleans, not null or nested objects.
With several filters, Datablist may first find items using one condition, then check the others and sort the matches on the server. You receive fully filtered results; you do not need to filter them again.
A request can be slower when that first condition matches many items. Choose filters that narrow the search. count limits the results returned, not all the items the server may need to check.
Arbitrary combinations of filters and ordering are not guaranteed. Multiple ordering fields are not supported for paginated or additionally filtered queries, and ordering a filtered query by a different field can require an unavailable index even without pagination. Use the combinations below for filtered pagination.
Missing fields are not automatically treated as empty strings or null values. Negative filters are not a way to find missing fields. Comparisons and ordering also require compatible field values; avoid mixing numbers, strings, and dates in a field you intend to compare or sort.

Ordering

Use order_by=FIELD_NAME for ascending order and order_by=-FIELD_NAME for descending order. For example, sort collection items by score:

Request

import requests

url = "https://api.datablist.com/v1/data/WORKSPACE_ID/collections/COLLECTION_ID/items"

headers = {
    "Accept": "application/json",
    "Authorization": "Bearer <token>"
}

params = {
    "order_by": "score"
}

response = requests.get(url, headers=headers, params=params)

print(response.text)

For descending order:

Request

import requests

url = "https://api.datablist.com/v1/data/WORKSPACE_ID/collections/COLLECTION_ID/items"

headers = {
    "Accept": "application/json",
    "Authorization": "Bearer <token>"
}

params = {
    "order_by": "-score"
}

response = requests.get(url, headers=headers, params=params)

print(response.text)

Filtering with pagination

For filtered calls using count or start_after_document_id, provide order_by with exactly one field, and include that field in the filters. You cannot paginate a filtered query while ordering by an unrelated field. For example, filter on score and order by score, rather than createdAt.

This call returns up to 25 US items with a score of at least 50, highest score first. The ordering field score is also a filtered field:

Request

import json
import requests

url = "https://api.datablist.com/v1/data/WORKSPACE_ID/collections/COLLECTION_ID/items"

headers = {
    "Accept": "application/json",
    "Authorization": "Bearer <token>"
}

filters = [{
    "name": "country",
    "op": "eq",
    "val": "US"
}, {
    "name": "score",
    "op": "ge",
    "val": 50
}]

params = {
    "order_by": "-score",
    "count": "25"
}
params["filter"] = json.dumps(filters, separators=(",", ":"))

response = requests.get(url, headers=headers, params=params)

print(response.text)

To request the next page, keep the same filters and ordering and pass the last returned item's ID as start_after_document_id:

Request

import json
import requests

url = "https://api.datablist.com/v1/data/WORKSPACE_ID/collections/COLLECTION_ID/items"

headers = {
    "Accept": "application/json",
    "Authorization": "Bearer <token>"
}

filters = [{
    "name": "country",
    "op": "eq",
    "val": "US"
}, {
    "name": "score",
    "op": "ge",
    "val": 50
}]

params = {
    "order_by": "-score",
    "count": "25",
    "start_after_document_id": "LAST_ITEM_ID"
}
params["filter"] = json.dumps(filters, separators=(",", ":"))

response = requests.get(url, headers=headers, params=params)

print(response.text)

Combination	Supported?
Filter `score >= 50`, order by `score` or `-score`, with `count`.	Yes.
Filter `country = US` and `score >= 50`, order by `score`, with `count` and an item cursor.	Yes; additional server-side filtering may be needed.
Filter `country = US`, order by `createdAt`, with `count`.	No: the ordering field is not in the filters.
Filters plus `count` or an item cursor, without `order_by`.	No: filtered pagination requires explicit ordering.
Pagination with `order_by=country,-score`.	No: pagination supports only one ordering field.
A property `in` filter with more than 30 values as the primary query, with `count` or a cursor.	No: this query is split into multiple lookups and cannot be paginated.

For a property in filter with 31–200 values, an unpaginated request can combine multiple lookups. If a different, suitable indexed condition drives the query, the large in list may instead be applied as an additional server-side filter. Do not rely on that optimization to make every large-list combination paginated. For predictable paginated calls, split the list into groups of at most 30 values, order by the filtered field, and paginate each group separately. Standalone @id lookups follow the ID-specific rules above.

Avoid adding a broad condition solely to satisfy the ordering rule: it may increase the amount of data read and does not ensure every combination is supported.

Delete an item

Delete an item →

Bulk create items

Create items in bulk →

Bulk update items

Bulk update operations take a list of ["item_id", {...}] tuples.

Bulk partial update

Update items in bulk →

Bulk full update

Replace items in bulk →

Bulk delete items

Delete items in bulk →

The Item object​

Properties​

Example​

Create an item​

Retrieve an item​

Update an item​

Partial​

Full update​

List all items​

Filtering​

Supported operators​

Equality​

Arrays and lists​

Ranges​

Text and empty values​

Dates​

Run Status​

Deprecated aliases​

Filter by item ID​

Combine filters​

Query limits and performance​

Ordering​

Filtering with pagination​

Delete an item​

Bulk create items​

Bulk update items​

Bulk partial update​

Bulk full update​

Bulk delete items​

The Item object

Properties

Example

Create an item

Retrieve an item

Update an item

Partial

Full update

List all items

Filtering

Supported operators

Equality

Arrays and lists

Ranges

Text and empty values

Dates

Run Status

Deprecated aliases

Filter by item ID

Combine filters

Query limits and performance

Ordering

Filtering with pagination

Delete an item

Bulk create items

Bulk update items

Bulk partial update

Bulk full update

Bulk delete items