---
updatedAt: 2025-10-11T08:52:31.000Z
agentTools:
  projectIndex: https://api-spreadsheet-docs.readme.io/llms.txt
---

# Read or delete data

Read data from your Spreadsheets/Google Sheets, optionally count matches, or delete rows when query beginning with `delete from` is provided.

# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "API Spreadsheets — Data API",
    "version": "1.0.1",
    "description": "Programmatic access to spreadsheet data.\n\n- **GET /data/{file_id}/** supports reading, counting, or deleting via the `query` parameter.\n  For GET, send `accessKey` and `secretKey` as **query** parameters.\n- **POST /data/{file_id}/** creates or updates rows.\n  For POST, send `accessKey` and `secretKey` as **headers** and a JSON body shaped like:\n  `{ \"data\": { \"<ColumnName>\": \"<Value>\", ... } }`.\n"
  },
  "servers": [
    {
      "url": "https://api.apispreadsheets.com"
    }
  ],
  "paths": {
    "/data/{file_id}/": {
      "parameters": [
        {
          "name": "file_id",
          "in": "path",
          "required": true,
          "description": "16-character alphanumeric file identifier.",
          "schema": {
            "type": "string",
            "pattern": "^[A-Za-z0-9]{16}$"
          }
        }
      ],
      "get": {
        "summary": "Read or delete data",
        "description": "Read data from your Spreadsheets/Google Sheets, optionally count matches, or delete rows when query beginning with `delete from` is provided.",
        "parameters": [
          {
            "name": "accessKey",
            "in": "header",
            "required": true,
            "description": "Access key credential unique to each file",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "secretKey",
            "in": "header",
            "required": true,
            "description": "Secret key credential unique to each file",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "query",
            "in": "query",
            "required": false,
            "description": "SQL-like statement for retrieving or deleting rows.\nExamples:   - Retrieve rows: \"select * from {file_id} where {column_name}='{cell_value}'\"   - Delete rows: \"delete from {file_id} where {column_name}='{cell_value}'\"\n",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of rows to return (only applies when using select).",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "dataFormat",
            "in": "query",
            "required": false,
            "description": "Format of returned data (only applies when using select).",
            "schema": {
              "type": "string",
              "enum": [
                "row",
                "column",
                "matrix"
              ],
              "default": "row"
            }
          },
          {
            "name": "count",
            "in": "query",
            "required": false,
            "description": "If present, response returns only the count of matching rows (only when reading data).",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. For reads, returns data or count. For deletes, returns a message (may vary).",
            "content": {
              "application/json": {
                "examples": {
                  "read": {
                    "summary": "Retrieve rows in default format",
                    "value": {
                      "data": [
                        {
                          "column_name": "cell_value",
                          "another_column": "another_value"
                        }
                      ]
                    }
                  },
                  "readMatrix": {
                    "summary": "Retrieve rows in matrix format (no column headers)",
                    "value": {
                      "data": [
                        [
                          "row_1_column_1_value",
                          "row_1_column_2_value"
                        ],
                        [
                          "row_2_column_1_value",
                          "row_2_column_2_value"
                        ]
                      ]
                    }
                  },
                  "readColumn": {
                    "summary": "Retrieve rows in column format",
                    "value": {
                      "column_1_name": [
                        "row_1_value",
                        "row_2_value"
                      ],
                      "column_2_name": [
                        "row_1_value",
                        "row_2_value"
                      ]
                    }
                  },
                  "delete": {
                    "summary": "Delete rows with delete",
                    "value": {
                      "message": "(n) rows deleted successfully."
                    }
                  },
                  "count": {
                    "summary": "Count example",
                    "value": {
                      "count": 42
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "examples": {
                  "invalidColumns": {
                    "summary": "Invalid columns",
                    "value": {
                      "error": "Your column names are not valid. Read our column name guide: https://www.apispreadsheets.com/api-docs/?docsMenuItem=upload-columnNames. Fix and try again."
                    }
                  },
                  "invalidQueryFilter": {
                    "summary": "Query filter failed",
                    "value": {
                      "error": "Your query is invalid. Check your filterClause (aka the stuff after the FROMfileIDWHERE..."
                    }
                  },
                  "invalidQueryMessage": {
                    "summary": "SQL validator message",
                    "value": {
                      "error": "Your SQL query syntax was incorrect. For e.g., query can only begin with SELECT or DELETE"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized (keys invalid for existing file)",
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "value": {
                      "error": "Your Keys Were Not Valid to Access this File"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Exceeded plan quota",
            "content": {
              "application/json": {
                "examples": {
                  "quotaExceeded": {
                    "value": {
                      "error": "You have exceeded the quota of your plan. Please upgrade to a higher payment plan"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "File not found",
            "content": {
              "application/json": {
                "examples": {
                  "notFound": {
                    "value": {
                      "error": "This file does not exist"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed (customer restrictions).",
            "content": {
              "application/json": {
                "examples": {
                  "readBlocked": {
                    "summary": "READ blocked",
                    "value": {
                      "error": "READ method is not allowed on your API due to customer request"
                    }
                  },
                  "deleteBlocked": {
                    "summary": "DELETE blocked",
                    "value": {
                      "error": "DELETE method is not allowed on your API due to customer request"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "examples": {
                  "generic": {
                    "value": {
                      "error": "Internal server error"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```