> For the complete documentation index, see [llms.txt](https://docs.humdata.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.humdata.org/build/hdx-apis/tabular-data-endpoints/openapi-specification.md).

# OpenAPI specification

Query these endpoints with curl or an API client, using your HDX token:

{% code overflow="wrap" %}

```
curl -H "Authorization: <your-api-token>" \  "https://data.humdata.org/api/3/action/datastore_search?resource_id=<resource-id>&limit=5"
```

{% endcode %}

For a GUI, import the [OpenAPI spec](https://raw.githubusercontent.com/OCHA-DAP/hdx-openapi-specs/main/dist/openapi.json) into Postman, Insomnia, Bruno, or Scalar and set an `Authorization` header. Get your token at **data.humdata.org → profile → Manage API tokens**.

## Get DataStore resource metadata

> Retrieve field definitions, type information, and size/count metadata for a DataStore resource.

```json
{"openapi":"3.1.0","info":{"title":"HDX APIs","version":"2.11.4"},"servers":[{"url":"https://data.humdata.org/api/3/action","description":"HDX Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"HDX API token. Required for all Tabular Data Endpoint requests, including public resources."}},"schemas":{"DatastoreInfoResponse":{"properties":{"help":{"description":"URL to the API documentation for this action.","title":"Help","type":"string"},"success":{"description":"Whether the request succeeded.","title":"Success","type":"boolean"},"result":{"$ref":"#/components/schemas/DatastoreInfoResult"}},"required":["help","success","result"],"title":"DatastoreInfoResponse","type":"object"},"DatastoreInfoResult":{"properties":{"meta":{"anyOf":[{"$ref":"#/components/schemas/DatastoreResourceMeta"},{"type":"null"}],"default":null,"description":"Resource metadata including aliases, row count, and size information."},"fields":{"description":"List of field descriptor objects. Each contains `id`, `type`, and optionally `schema` with index and uniqueness information.","items":{"additionalProperties":true,"type":"object"},"title":"Fields","type":"array"}},"required":["fields"],"title":"DatastoreInfoResult","type":"object"},"DatastoreResourceMeta":{"properties":{"aliases":{"description":"List of aliases defined for this resource.","items":{"type":"string"},"title":"Aliases","type":"array"},"count":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Total number of rows in the resource table.","title":"Count"},"db_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Total size of the DataStore database in bytes (all tables, not just this resource).","title":"Db Size"},"id":{"description":"The resource ID.","title":"Id","type":"string"},"idx_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Size of indexes on this resource table in bytes.","title":"Idx Size"},"size":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Size of this resource table in bytes.","title":"Size"},"table_type":{"anyOf":[{"enum":["BASE TABLE","VIEW","FOREIGN","LOCAL TEMPORARY"],"type":"string"},{"type":"null"}],"default":null,"description":"PostgreSQL table type for this resource.","title":"Table Type"}},"required":["aliases","id"],"title":"DatastoreResourceMeta","type":"object"},"ErrorResponse":{"properties":{"success":{"default":false,"description":"Always false for error responses.","title":"Success","type":"boolean"},"error":{"additionalProperties":true,"description":"Error detail object. Always contains a '__type' string. 403/404 errors include a 'message'; validation (409) errors instead carry structured 'query'/'info' fields.","title":"Error","type":"object"}},"required":["error"],"title":"ErrorResponse","type":"object"}}},"paths":{"/datastore_info":{"get":{"operationId":"datastore_info_get","summary":"Get DataStore resource metadata","description":"Retrieve field definitions, type information, and size/count metadata for a DataStore resource.","tags":["DataStore"],"parameters":[{"name":"resource_id","in":"query","required":true,"schema":{"title":"Resource Id","type":"string"},"description":"The `id` or alias of the DataStore resource to describe. Required."}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatastoreInfoResponse"}}}},"403":{"description":"Forbidden — API token is missing or invalid. Authentication is required for all DataStore requests, including public resources.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found — the resource_id does not exist in the DataStore.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — Validation Error. The request parameters or SQL were invalid (e.g. missing required parameter, non-SELECT SQL, malformed query, or wrong parameter type).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests — rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error — unexpected server-side failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Get DataStore resource metadata (POST)

> Identical to the GET form.

```json
{"openapi":"3.1.0","info":{"title":"HDX APIs","version":"2.11.4"},"servers":[{"url":"https://data.humdata.org/api/3/action","description":"HDX Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"HDX API token. Required for all Tabular Data Endpoint requests, including public resources."}},"schemas":{"DatastoreInfoParams":{"properties":{"resource_id":{"description":"The `id` or alias of the DataStore resource to describe. Required.","title":"Resource Id","type":"string"}},"required":["resource_id"],"title":"DatastoreInfoParams","type":"object"},"DatastoreInfoResponse":{"properties":{"help":{"description":"URL to the API documentation for this action.","title":"Help","type":"string"},"success":{"description":"Whether the request succeeded.","title":"Success","type":"boolean"},"result":{"$ref":"#/components/schemas/DatastoreInfoResult"}},"required":["help","success","result"],"title":"DatastoreInfoResponse","type":"object"},"DatastoreInfoResult":{"properties":{"meta":{"anyOf":[{"$ref":"#/components/schemas/DatastoreResourceMeta"},{"type":"null"}],"default":null,"description":"Resource metadata including aliases, row count, and size information."},"fields":{"description":"List of field descriptor objects. Each contains `id`, `type`, and optionally `schema` with index and uniqueness information.","items":{"additionalProperties":true,"type":"object"},"title":"Fields","type":"array"}},"required":["fields"],"title":"DatastoreInfoResult","type":"object"},"DatastoreResourceMeta":{"properties":{"aliases":{"description":"List of aliases defined for this resource.","items":{"type":"string"},"title":"Aliases","type":"array"},"count":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Total number of rows in the resource table.","title":"Count"},"db_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Total size of the DataStore database in bytes (all tables, not just this resource).","title":"Db Size"},"id":{"description":"The resource ID.","title":"Id","type":"string"},"idx_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Size of indexes on this resource table in bytes.","title":"Idx Size"},"size":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Size of this resource table in bytes.","title":"Size"},"table_type":{"anyOf":[{"enum":["BASE TABLE","VIEW","FOREIGN","LOCAL TEMPORARY"],"type":"string"},{"type":"null"}],"default":null,"description":"PostgreSQL table type for this resource.","title":"Table Type"}},"required":["aliases","id"],"title":"DatastoreResourceMeta","type":"object"},"ErrorResponse":{"properties":{"success":{"default":false,"description":"Always false for error responses.","title":"Success","type":"boolean"},"error":{"additionalProperties":true,"description":"Error detail object. Always contains a '__type' string. 403/404 errors include a 'message'; validation (409) errors instead carry structured 'query'/'info' fields.","title":"Error","type":"object"}},"required":["error"],"title":"ErrorResponse","type":"object"}}},"paths":{"/datastore_info":{"post":{"operationId":"datastore_info_post","summary":"Get DataStore resource metadata (POST)","description":"Identical to the GET form.","tags":["DataStore"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatastoreInfoParams"}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatastoreInfoResponse"}}}},"403":{"description":"Forbidden — API token is missing or invalid. Authentication is required for all DataStore requests, including public resources.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found — the resource_id does not exist in the DataStore.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — Validation Error. The request parameters or SQL were invalid (e.g. missing required parameter, non-SELECT SQL, malformed query, or wrong parameter type).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests — rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error — unexpected server-side failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Search a DataStore resource

> Query rows from a DataStore resource with optional filtering, full-text search, sorting, and pagination.\
> \
> Pass parameters as query string arguments (GET) or as a JSON body (POST).

```json
{"openapi":"3.1.0","info":{"title":"HDX APIs","version":"2.11.4"},"servers":[{"url":"https://data.humdata.org/api/3/action","description":"HDX Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"HDX API token. Required for all Tabular Data Endpoint requests, including public resources."}},"schemas":{"DatastoreSearchResponse":{"properties":{"help":{"description":"URL to the API documentation for this action.","title":"Help","type":"string"},"success":{"description":"Whether the request succeeded.","title":"Success","type":"boolean"},"result":{"$ref":"#/components/schemas/DatastoreSearchResult"}},"required":["help","success","result"],"title":"DatastoreSearchResponse","type":"object"},"DatastoreSearchResult":{"properties":{"resource_id":{"description":"The resource ID that was queried.","title":"Resource Id","type":"string"},"fields":{"description":"List of field descriptor objects, each with `id` and `type` keys.","items":{"additionalProperties":true,"type":"object"},"title":"Fields","type":"array"},"offset":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"The offset used in the query.","title":"Offset"},"limit":{"description":"The limit used in the query.","title":"Limit","type":"integer"},"filters":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"Filters applied to the query.","title":"Filters"},"include_total":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"Echoed from the request parameter. Indicates whether `total` is included.","title":"Include Total"},"records_format":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Echoed from the request parameter. Format used for `records`.","title":"Records Format"},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Total number of matching rows. Present when `include_total` is `true`.","title":"Total"},"total_was_estimated":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"Whether the total count was estimated rather than exact.","title":"Total Was Estimated"},"total_estimation_threshold":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Row count threshold above which total estimation is used. `null` when estimation is not configured.","title":"Total Estimation Threshold"},"records":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"items":{"items":{},"type":"array"},"type":"array"},{"type":"string"}],"description":"Matching rows. Shape depends on `records_format`.","title":"Records"},"_links":{"$ref":"#/components/schemas/DatastoreSearchLinks","description":"Pagination helper URLs. Always present — `next` contains the URL for the next page of results."}},"required":["resource_id","fields","limit","records","_links"],"title":"DatastoreSearchResult","type":"object"},"DatastoreSearchLinks":{"properties":{"start":{"description":"URL to the first page of results with the same parameters.","title":"Start","type":"string"},"next":{"description":"URL to the next page of results.","title":"Next","type":"string"}},"required":["start","next"],"title":"DatastoreSearchLinks","type":"object"},"ErrorResponse":{"properties":{"success":{"default":false,"description":"Always false for error responses.","title":"Success","type":"boolean"},"error":{"additionalProperties":true,"description":"Error detail object. Always contains a '__type' string. 403/404 errors include a 'message'; validation (409) errors instead carry structured 'query'/'info' fields.","title":"Error","type":"object"}},"required":["error"],"title":"ErrorResponse","type":"object"}}},"paths":{"/datastore_search":{"get":{"operationId":"datastore_search_get","summary":"Search a DataStore resource","description":"Query rows from a DataStore resource with optional filtering, full-text search, sorting, and pagination.\n\nPass parameters as query string arguments (GET) or as a JSON body (POST).","tags":["DataStore"],"parameters":[{"name":"resource_id","in":"query","required":true,"schema":{"title":"Resource Id","type":"string"},"description":"The `id` or alias of the resource to search. Required."},{"name":"filters","in":"query","required":false,"schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Filters"},"description":"Matching conditions as a dictionary of `{field: value}` pairs. Rows must match all conditions. Example: `{\"country\": \"Uganda\"}`."},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Q"},"description":"Full-text search query. Pass a string to search across all fields, or a dictionary of `{field: query}` to target specific fields. Note: behavior differs subtly from `filters` — `q` uses full-text ranking while `filters` performs exact matching."},{"name":"full_text","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Full Text"},"description":"Full-text search query applied across all fields. Similar to `q` with a string value, but always searches all fields. Cannot be combined with `q`."},{"name":"distinct","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"title":"Distinct"},"description":"Return only unique rows. Defaults to `false`."},{"name":"plain","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"title":"Plain"},"description":"Treat the `q` query as plain text (no special FTS operators). Set to `false` to use PostgreSQL tsquery syntax. Defaults to `true`."},{"name":"language","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":"english","title":"Language"},"description":"Language used for full-text search stemming. Defaults to `english`."},{"name":"limit","in":"query","required":false,"schema":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":100,"title":"Limit"},"description":"Maximum number of rows to return. Defaults to `100`."},{"name":"offset","in":"query","required":false,"schema":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"title":"Offset"},"description":"Number of rows to skip before returning results. Used for pagination."},{"name":"fields","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"string"},{"type":"null"}],"default":null,"title":"Fields"},"description":"Columns to include in the response. Pass a comma-separated string or a list. Defaults to all fields."},{"name":"sort","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sort"},"description":"Comma-separated list of fields to sort by, with optional `asc`/`desc` direction. Example: `\"fieldname1 asc, fieldname2 desc\"`."},{"name":"include_total","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"title":"Include Total"},"description":"Include the total number of matching rows in the response. Defaults to `true`."},{"name":"total_estimation_threshold","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Total Estimation Threshold"},"description":"When `include_total` is `true` and the estimated row count exceeds this threshold, CKAN returns an estimated total rather than an exact count. Set to `null` (default) to always return an exact count."},{"name":"records_format","in":"query","required":false,"schema":{"anyOf":[{"enum":["objects","lists","csv","tsv"],"type":"string"},{"type":"null"}],"default":"objects","title":"Records Format"},"description":"Format for the returned records. `objects` returns a list of dicts, `lists` returns a list of lists, `csv` and `tsv` return delimited strings. Defaults to `objects`."}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatastoreSearchResponse"}}}},"403":{"description":"Forbidden — API token is missing or invalid. Authentication is required for all DataStore requests, including public resources.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found — the resource_id does not exist in the DataStore.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — Validation Error. The request parameters or SQL were invalid (e.g. missing required parameter, non-SELECT SQL, malformed query, or wrong parameter type).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests — rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error — unexpected server-side failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Search a DataStore resource (POST)

> Identical to the GET form. Use POST to pass parameters as a JSON body, which is useful for large \`filters\` or \`fields\` payloads.

```json
{"openapi":"3.1.0","info":{"title":"HDX APIs","version":"2.11.4"},"servers":[{"url":"https://data.humdata.org/api/3/action","description":"HDX Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"HDX API token. Required for all Tabular Data Endpoint requests, including public resources."}},"schemas":{"DatastoreSearchParams":{"properties":{"resource_id":{"description":"The `id` or alias of the resource to search. Required.","title":"Resource Id","type":"string"},"filters":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"Matching conditions as a dictionary of `{field: value}` pairs. Rows must match all conditions. Example: `{\"country\": \"Uganda\"}`.","title":"Filters"},"q":{"anyOf":[{"type":"string"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"Full-text search query. Pass a string to search across all fields, or a dictionary of `{field: query}` to target specific fields. Note: behavior differs subtly from `filters` — `q` uses full-text ranking while `filters` performs exact matching.","title":"Q"},"full_text":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Full-text search query applied across all fields. Similar to `q` with a string value, but always searches all fields. Cannot be combined with `q`.","title":"Full Text"},"distinct":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"Return only unique rows. Defaults to `false`.","title":"Distinct"},"plain":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"Treat the `q` query as plain text (no special FTS operators). Set to `false` to use PostgreSQL tsquery syntax. Defaults to `true`.","title":"Plain"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"default":"english","description":"Language used for full-text search stemming. Defaults to `english`.","title":"Language"},"limit":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":100,"description":"Maximum number of rows to return. Defaults to `100`.","title":"Limit"},"offset":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Number of rows to skip before returning results. Used for pagination.","title":"Offset"},"fields":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"string"},{"type":"null"}],"default":null,"description":"Columns to include in the response. Pass a comma-separated string or a list. Defaults to all fields.","title":"Fields"},"sort":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated list of fields to sort by, with optional `asc`/`desc` direction. Example: `\"fieldname1 asc, fieldname2 desc\"`.","title":"Sort"},"include_total":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"Include the total number of matching rows in the response. Defaults to `true`.","title":"Include Total"},"total_estimation_threshold":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"When `include_total` is `true` and the estimated row count exceeds this threshold, CKAN returns an estimated total rather than an exact count. Set to `null` (default) to always return an exact count.","title":"Total Estimation Threshold"},"records_format":{"anyOf":[{"enum":["objects","lists","csv","tsv"],"type":"string"},{"type":"null"}],"default":"objects","description":"Format for the returned records. `objects` returns a list of dicts, `lists` returns a list of lists, `csv` and `tsv` return delimited strings. Defaults to `objects`.","title":"Records Format"}},"required":["resource_id"],"title":"DatastoreSearchParams","type":"object"},"DatastoreSearchResponse":{"properties":{"help":{"description":"URL to the API documentation for this action.","title":"Help","type":"string"},"success":{"description":"Whether the request succeeded.","title":"Success","type":"boolean"},"result":{"$ref":"#/components/schemas/DatastoreSearchResult"}},"required":["help","success","result"],"title":"DatastoreSearchResponse","type":"object"},"DatastoreSearchResult":{"properties":{"resource_id":{"description":"The resource ID that was queried.","title":"Resource Id","type":"string"},"fields":{"description":"List of field descriptor objects, each with `id` and `type` keys.","items":{"additionalProperties":true,"type":"object"},"title":"Fields","type":"array"},"offset":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"The offset used in the query.","title":"Offset"},"limit":{"description":"The limit used in the query.","title":"Limit","type":"integer"},"filters":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"Filters applied to the query.","title":"Filters"},"include_total":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"Echoed from the request parameter. Indicates whether `total` is included.","title":"Include Total"},"records_format":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Echoed from the request parameter. Format used for `records`.","title":"Records Format"},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Total number of matching rows. Present when `include_total` is `true`.","title":"Total"},"total_was_estimated":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"Whether the total count was estimated rather than exact.","title":"Total Was Estimated"},"total_estimation_threshold":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Row count threshold above which total estimation is used. `null` when estimation is not configured.","title":"Total Estimation Threshold"},"records":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"items":{"items":{},"type":"array"},"type":"array"},{"type":"string"}],"description":"Matching rows. Shape depends on `records_format`.","title":"Records"},"_links":{"$ref":"#/components/schemas/DatastoreSearchLinks","description":"Pagination helper URLs. Always present — `next` contains the URL for the next page of results."}},"required":["resource_id","fields","limit","records","_links"],"title":"DatastoreSearchResult","type":"object"},"DatastoreSearchLinks":{"properties":{"start":{"description":"URL to the first page of results with the same parameters.","title":"Start","type":"string"},"next":{"description":"URL to the next page of results.","title":"Next","type":"string"}},"required":["start","next"],"title":"DatastoreSearchLinks","type":"object"},"ErrorResponse":{"properties":{"success":{"default":false,"description":"Always false for error responses.","title":"Success","type":"boolean"},"error":{"additionalProperties":true,"description":"Error detail object. Always contains a '__type' string. 403/404 errors include a 'message'; validation (409) errors instead carry structured 'query'/'info' fields.","title":"Error","type":"object"}},"required":["error"],"title":"ErrorResponse","type":"object"}}},"paths":{"/datastore_search":{"post":{"operationId":"datastore_search_post","summary":"Search a DataStore resource (POST)","description":"Identical to the GET form. Use POST to pass parameters as a JSON body, which is useful for large `filters` or `fields` payloads.","tags":["DataStore"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatastoreSearchParams"}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatastoreSearchResponse"}}}},"403":{"description":"Forbidden — API token is missing or invalid. Authentication is required for all DataStore requests, including public resources.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found — the resource_id does not exist in the DataStore.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — Validation Error. The request parameters or SQL were invalid (e.g. missing required parameter, non-SELECT SQL, malformed query, or wrong parameter type).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests — rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error — unexpected server-side failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Query a DataStore resource with SQL

> Execute a SQL \`SELECT\` statement against one or more DataStore resources. Useful for aggregations, joins, and complex filtering that \`datastore\_search\` cannot express.\
> \
> Only \`SELECT\` statements are permitted.

```json
{"openapi":"3.1.0","info":{"title":"HDX APIs","version":"2.11.4"},"servers":[{"url":"https://data.humdata.org/api/3/action","description":"HDX Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"HDX API token. Required for all Tabular Data Endpoint requests, including public resources."}},"schemas":{"DatastoreSearchSqlResponse":{"properties":{"help":{"description":"URL to the API documentation for this action.","title":"Help","type":"string"},"success":{"description":"Whether the request succeeded.","title":"Success","type":"boolean"},"result":{"$ref":"#/components/schemas/DatastoreSearchSqlResult"}},"required":["help","success","result"],"title":"DatastoreSearchSqlResponse","type":"object"},"DatastoreSearchSqlResult":{"properties":{"sql":{"description":"The SQL query echoed back from the request.","title":"Sql","type":"string"},"fields":{"description":"List of field descriptor objects for the result columns, each with `id` and `type` keys.","items":{"additionalProperties":true,"type":"object"},"title":"Fields","type":"array"},"records":{"description":"List of result row objects.","items":{"additionalProperties":true,"type":"object"},"title":"Records","type":"array"},"records_truncated":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"Present and `true` if the result set was truncated at the server-side 32,000-row limit.","title":"Records Truncated"}},"required":["sql","fields","records"],"title":"DatastoreSearchSqlResult","type":"object"},"ErrorResponse":{"properties":{"success":{"default":false,"description":"Always false for error responses.","title":"Success","type":"boolean"},"error":{"additionalProperties":true,"description":"Error detail object. Always contains a '__type' string. 403/404 errors include a 'message'; validation (409) errors instead carry structured 'query'/'info' fields.","title":"Error","type":"object"}},"required":["error"],"title":"ErrorResponse","type":"object"}}},"paths":{"/datastore_search_sql":{"get":{"operationId":"datastore_search_sql_get","summary":"Query a DataStore resource with SQL","description":"Execute a SQL `SELECT` statement against one or more DataStore resources. Useful for aggregations, joins, and complex filtering that `datastore_search` cannot express.\n\nOnly `SELECT` statements are permitted.","tags":["DataStore"],"parameters":[{"name":"sql","in":"query","required":true,"schema":{"title":"Sql","type":"string"},"description":"A single SQL `SELECT` statement to execute against the DataStore. Required. Only `SELECT` statements are permitted — `INSERT`, `UPDATE`, `DELETE`, and DDL statements are not allowed. Table names correspond to resource IDs (e.g. `SELECT * FROM \"<resource_id>\"`)."}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatastoreSearchSqlResponse"}}}},"403":{"description":"Forbidden — API token is missing or invalid. Authentication is required for all DataStore requests, including public resources.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found — the resource_id does not exist in the DataStore.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — Validation Error. The request parameters or SQL were invalid (e.g. missing required parameter, non-SELECT SQL, malformed query, or wrong parameter type).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests — rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error — unexpected server-side failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Query a DataStore resource with SQL (POST)

> Identical to the GET form. Use POST for long SQL statements.

```json
{"openapi":"3.1.0","info":{"title":"HDX APIs","version":"2.11.4"},"servers":[{"url":"https://data.humdata.org/api/3/action","description":"HDX Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"HDX API token. Required for all Tabular Data Endpoint requests, including public resources."}},"schemas":{"DatastoreSearchSqlParams":{"properties":{"sql":{"description":"A single SQL `SELECT` statement to execute against the DataStore. Required. Only `SELECT` statements are permitted — `INSERT`, `UPDATE`, `DELETE`, and DDL statements are not allowed. Table names correspond to resource IDs (e.g. `SELECT * FROM \"<resource_id>\"`).","title":"Sql","type":"string"}},"required":["sql"],"title":"DatastoreSearchSqlParams","type":"object"},"DatastoreSearchSqlResponse":{"properties":{"help":{"description":"URL to the API documentation for this action.","title":"Help","type":"string"},"success":{"description":"Whether the request succeeded.","title":"Success","type":"boolean"},"result":{"$ref":"#/components/schemas/DatastoreSearchSqlResult"}},"required":["help","success","result"],"title":"DatastoreSearchSqlResponse","type":"object"},"DatastoreSearchSqlResult":{"properties":{"sql":{"description":"The SQL query echoed back from the request.","title":"Sql","type":"string"},"fields":{"description":"List of field descriptor objects for the result columns, each with `id` and `type` keys.","items":{"additionalProperties":true,"type":"object"},"title":"Fields","type":"array"},"records":{"description":"List of result row objects.","items":{"additionalProperties":true,"type":"object"},"title":"Records","type":"array"},"records_truncated":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"Present and `true` if the result set was truncated at the server-side 32,000-row limit.","title":"Records Truncated"}},"required":["sql","fields","records"],"title":"DatastoreSearchSqlResult","type":"object"},"ErrorResponse":{"properties":{"success":{"default":false,"description":"Always false for error responses.","title":"Success","type":"boolean"},"error":{"additionalProperties":true,"description":"Error detail object. Always contains a '__type' string. 403/404 errors include a 'message'; validation (409) errors instead carry structured 'query'/'info' fields.","title":"Error","type":"object"}},"required":["error"],"title":"ErrorResponse","type":"object"}}},"paths":{"/datastore_search_sql":{"post":{"operationId":"datastore_search_sql_post","summary":"Query a DataStore resource with SQL (POST)","description":"Identical to the GET form. Use POST for long SQL statements.","tags":["DataStore"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatastoreSearchSqlParams"}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatastoreSearchSqlResponse"}}}},"403":{"description":"Forbidden — API token is missing or invalid. Authentication is required for all DataStore requests, including public resources.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found — the resource_id does not exist in the DataStore.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — Validation Error. The request parameters or SQL were invalid (e.g. missing required parameter, non-SELECT SQL, malformed query, or wrong parameter type).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests — rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error — unexpected server-side failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.humdata.org/build/hdx-apis/tabular-data-endpoints/openapi-specification.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.