List records of a Tulip Table

01 Oct 2024
5 Minutes to read
Contributors

List records of a Tulip Table

Updated on 01 Oct 2024
5 Minutes to read
Contributors

Article summary

Did you find this summary helpful?

Thank you for your feedback

Get

/tables/{tableId}/records

Lists the records in a Tulip Table, optionally filtered by the query parameters.

Requires the tables:read API key scope.

Security

HTTP

Type basic

A Tulip API key is required to use the Tulip API. API key authentication uses HTTP Basic Authentication as defined by RFC 7617. HTTP Basic Authentication uses a generic username/password scheme to authenticate. For Tulip API requests, the password should be the API key's associated secret. The username should have the format {type}.{version}_{id}, where {type} is the API key type, {version} is the type's version number, and {id} is the id of the key. Tulip API keys currently are one of two types:

apikey.2 - user API keys provisioned by creating a Tulip API Token. The key id is the token id.
onetime.1 - temporary API keys provisioned using the /auth/temporary endpoint or using the One-Time API Key page. These keys are only valid for 30 seconds after provisioning.

Once you have determined the username and password you need to use, the Authorization header should be set to the value Basic {credentials}, where {credentials} is the base64-encoded value of the string {username}:{password}. See RFC 7617 for more details of this encoding.

Path parameters

tableId

stringRequired

The id of a Tulip Table.

Pattern^[a-zA-Z0-9_]+$

Exampleg56RCoZCtzv7borvp

Query parameters

limit

integer

A limit for how many records should be returned in the response. At most this many records will be returned. To determine if there are more records beyond those included in the response, use the includeTotalCount query parameter. Defaults to 10 records and cannot be more than 100 records.

Minimum1

Maximum100

Default10

offset

integer

The index of the record to start at. The exact order of returned records depends on the sortBy and sortDir parameters. This parameter is usually used for pagination.

Minimum0

Default0

includeTotalCount

boolean

If this flag is set, the total number of records in the Table which match the filters is returned in the X-Total-Count header in the response. Determining this count requires an extra (potentially expensive) database query, so clients should omit this flag if the total count is not needed.

Defaultfalse

filters

Array of object

An optional array of filter expressions to filter the Table records by. Each filter is an object specifying the field (name of a table column), functionType (comparison function), and arg (the value to compare to).

The field may be the name of a table column (including id) or one of these special values:

_createdAt
_updatedAt

The valid function types are:

equal
notEqual
blank
notBlank
greaterThanOrEqual
lessThanOrEqual
greaterThan
lessThan
contains
notContains
startsWith
notStartsWith
endsWith
notEndsWith
isIn
notIsIn

Note: The isIn and notIsIn functions take in array inputs. To pass an array input into a connector function you must convert the array to a string of this format: ["1", "2", "3"]. Also, the blank and notBlank functions do not take in any arguments at all.

Example: [{"field": "field1", "functionType": "equal", "arg": "1"},{"field": "field2", "functionType": "notBlank"}, {"field": "field3", "functionType": "isIn", "arg": ["1", "2", "3"]}]

object

field

string Required

functionType

string Required

Valid values[ "equal", "notEqual", "blank", "notBlank", "greaterThanOrEqual", "lessThanOrEqual", "greaterThan", "lessThan", "contains", "notContains", "startsWith", "notStartsWith", "endsWith", "notEndsWith", "isIn", "notIsIn" ]

arg

string

fields

array of string

Specifiying fields allows to reduce the amount of data returned in the result to just the data for each of the fields specified. If ommitted, all fields for a given record will be returned. A field value that is not one of the table's fields will generate a 422 error.

Example: ["ipwkk_weight", "cyveu_completed", "id", "_updatedAt", "bDabBK8jmxZqWY8iT_link_left_column"]

filterAggregator

string

How the filters in the filters parameter are combined.

all means that every filter must match a record in order for the record to be included.
any means at least one filter must match a record in order for the record to be included.

Valid values[ "all", "any" ]

Default"all"

sortOptions

Array of object

Sorting allows to define which records are considered if there are more than the specified limit. Sort priority is determined by the order or options, i.e. sort by the first option, them by the second, etc. If ommitted, there is no guarantee as to which records are selected. A sortBy value that is not one of the table's field will generate a 422 error. Options for sortDir are "asc" and "desc".

Example: [{"sortBy": "superAwesomeField", "sortDir": "asc"}, {"sortBy": "lessAwesomeField", "sortDir": "desc"}]

object

Sorts are used to order the queries based on columns defined in the Tulip Table where the query exists.

Example{ "sortBy": "Color", "sortDir": "asc" }

sortBy

string Required

The field that records should be sorted by in the response. Can be the name of any of the columns of the Table (including id) or one of these special values:

_sequenceNumber
_createdAt
_updatedAt

sortDir

string Required

The direction of the records, either acsending or descending

Valid values[ "asc", "desc" ]

Default"asc"

Responses

200

The list of Tulip Table records was retrieved successfully.

Headers

X-Total-Count

integer

The total number of records in the Table which match the filters. Only returned if the `includeTotalCount` query parameter is set.

Minimum0

Array of object

object

A single record stored in a Tulip Table. The record object will include the names and values of all columns of the Table that are not hidden, in addition to the record's sequence number, created timestamp, and last updated timestamp.

Example{ "_sequenceNumber": 15, "_createdAt": "2019-02-08T20:16:31Z", "_updatedAt": "2019-02-08T20:16:31Z", "id": "bike-a", "ahvbb_model_number": "AAA", "auznd_color": "blue", "irrip_completed": true, "umiyk_durability_test_duration": 123000 }

_sequenceNumber

integer

A monotonically increasing unique identifier for this record.

_createdAt

string (date-time)

_updatedAt

string (date-time)

400

The request was malformed. This could mean that headers, query parameters, or the request body was unable to be parsed or had unexpected values.

object

errorCode

string

errorUniqueID

string

Pattern^[a-zA-Z0-9+/]+$

Exampleaq21mSKC1rbO87TjC/4Hz2EJHd/v+jxf7MtC315vo0Y

details

string

401

The request was made unauthorized. HTTP Basic Authorization using a Tulip API Key is required for use of the API.

object

errorCode

string

errorUniqueID

string

Pattern^[a-zA-Z0-9+/]+$

Exampleaq21mSKC1rbO87TjC/4Hz2EJHd/v+jxf7MtC315vo0Y

details

string

errorCode

Valid values[ "AuthenticationRequired" ]

403

The provided authentication info was rejected. The response will provide additional details.

object

errorCode

string

errorUniqueID

string

Pattern^[a-zA-Z0-9+/]+$

Exampleaq21mSKC1rbO87TjC/4Hz2EJHd/v+jxf7MtC315vo0Y

details

string

errorCode

Valid values[ "AuthenticationFailed" ]

404

The requested database entry was not found.

object

errorCode

string

errorUniqueID

string

Pattern^[a-zA-Z0-9+/]+$

Exampleaq21mSKC1rbO87TjC/4Hz2EJHd/v+jxf7MtC315vo0Y

details

string

errorCode

Valid values[ "NoSuchDatabaseEntry" ]

422

The request was syntactically sound, but could not be processed due to a logical problem.

object

errorCode

string

errorUniqueID

string

Pattern^[a-zA-Z0-9+/]+$

Exampleaq21mSKC1rbO87TjC/4Hz2EJHd/v+jxf7MtC315vo0Y

details

string

errorCode

Valid values[ "UnprocessableEntity" ]

500

The server encountered an unexpected error.

object

errorCode

string

errorUniqueID

string

Pattern^[a-zA-Z0-9+/]+$

Exampleaq21mSKC1rbO87TjC/4Hz2EJHd/v+jxf7MtC315vo0Y

details

string

Was this article helpful?

What's Next

Create a Tulip Table record