Read

GET/api/v1/{API_ID}

Get content

Returns an array with all data from the spreadsheet.

Optional attributes

Name
sheet
Type
string
Description
The sheet (tab) you want to select.
Name
limit
Type
integer
Description
Limit the number of rows returned.
Name
offset
Type
integer
Description
Which result to start with (how many results to skip).
Name
sort_by
Type
string
Description
The name of the column by which you want to sort the results.
Name
sort_order
Type
string
Description
Sort order. You can choose:
- asc - sort in ascending order
- desc - sort in descending order
- random - get data in random order
Name
sort_method
Type
string
Description
If you want to sort by date, set this attribute to date, SheetDB will try to automatically detect the data format but it is recommended to specify the format in the sort_date_format attribute.
Name
sort_date_format
Type
string
Description
Date format, e.g. if your date is 2022-19-12 use Y-m-d. For date time like 2022-19-12 13:55:00 use Y-m-d H:i:s.
Applies only when sort_method=date.
Name
cast_numbers
Type
string
Description
If you want to cast a value into a number, use its column name here. You can use multiple column names separated by commas.
Example: https://sheetdb.io/api/v1/58f61be4dda40?cast_numbers=id,age
Name
single_object
Type
boolean
Description
If you want to get only one row as an object (not in an array), set this attribute to true.
Name
mode
Type
string
Description
Value Render Option, more info here.

Request

GET

/api/v1/{API_ID}

# Sort results by id in descending order, take two
# and return the age as an integer.

curl -G https://sheetdb.io/api/v1/58f61be4dda40 \
  -d sort_by=id \
  -d sort_order=desc \
  -d limit=2 \
  -d cast_numbers=age

JSON Response

[
    {
        "id": "5",
        "name": "James",
        "age": 19,
        "comment": ""
    },
    {
        "id": "4",
        "name": "Steve",
        "age": 22,
        "comment": "special"
    }
]

GET/api/v1/{API_ID}/keys

Keys

Returns an array with all column names. It's all the cells from the first row.

Request

GET

/api/v1/{API_ID}

# Sort results by id in descending order, take two
# and return the age as an integer.

curl -G https://sheetdb.io/api/v1/58f61be4dda40/keys

JSON Response

[
    "id",
    "name",
    "age",
    "comment"
]

GET/api/v1/{API_ID}/name

Document name

Returns the name of the document.

JSON Response

{
    "name": "SheetDB test document"
}

GET/api/v1/{API_ID}/count

Count

Returns the number of rows in the document (without first row).

The rows are counted from the same cache that the Get content endpoint is served from, so the result may be out of date for up to the cache lifetime: the time set in your API settings when the cache is enabled, or 15 seconds when the cache is disabled.

Changes made through the SheetDB API (POST, PATCH, PUT, DELETE) clear the cache, so the next /count request returns a fresh value. Changes made directly in Google Sheets do not clear the cache and will be reflected only after it expires.

If you need a live count, add the ignore_cache=1 parameter, example: https://sheetdb.io/api/v1/58f61be4dda40/count?ignore_cache=1. This request also refreshes the cache used by the Get content endpoint.

The mode attribute has no effect on this endpoint. The rows are always counted from the data in the default FORMATTED_VALUE mode.

If the sheet attribute points to a sheet (tab) that does not exist, you will receive a 404 error with {"error": "Sheet not found."}.

Optional attributes

Name
sheet
Type
string
Description
The sheet (tab) you want to select.
Name
ignore_cache
Type
boolean
Description
Set to 1 to bypass the cache and count the rows directly from Google Sheets.

JSON Response

{
    "rows": 5
}