# Describe a cloud GeoParquet dataset

> Index of the TerraLab docs for agents: [llms.txt](https://terra-lab.ai/docs/llms.txt). Every docs page is also served as markdown: add .md to its URL.

What a public cloud GeoParquet holds, read from its footer only: rows, columns with their ranges, geometry, CRS, extent and partitions.

| | |
| --- | --- |
| REST | `POST https://mcp.terra-lab.ai/v1/tools/inspect_dataset` |
| MCP tool | `inspect_dataset` on `https://mcp.terra-lab.ai/mcp` |
| Group | Data catalog |

## Request

```bash
curl -X POST https://mcp.terra-lab.ai/v1/tools/inspect_dataset \
  -H "Authorization: Bearer $TERRALAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dataset":"portolan:nasa-firms-active-fire/detections"}'
```

```python
import os
import requests

response = requests.post(
    "https://mcp.terra-lab.ai/v1/tools/inspect_dataset",
    headers={"Authorization": f"Bearer {os.environ['TERRALAB_API_KEY']}"},
    json={
        "dataset": "portolan:nasa-firms-active-fire/detections",
    },
    timeout=120,
)
response.raise_for_status()
print(response.json()["structuredContent"])
```

```javascript
const response = await fetch('https://mcp.terra-lab.ai/v1/tools/inspect_dataset', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TERRALAB_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "dataset": "portolan:nasa-firms-active-fire/detections"
  }),
});
const data = await response.json();
console.log(data.structuredContent);
```

## Parameters

A JSON object in the request body; in an MCP client, the arguments of the tool call.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `dataset` | string | Yes | A portolan: id from find_datasets (open_registry), or the https URL of a public GeoParquet file, a hive glob such as https://.../year=*/data.parquet, an s3:// or gs:// address, or a STAC collection.json. Up to 400 characters. |

## Response

`structuredContent` holds the result, `content` the same result as text for a model, and `isError` is `true` when the tool refused the request or failed; then `structuredContent.code`, `message` and `hint` say what to change.

```json
{
  "structuredContent": {
    "sources": [{ "name": "...", "licence": "...", "url": "..." }],
    "downloads": [{ "label": "...", "format": "...", "url": "...", "name": "..." }]
  },
  "content": [{ "type": "text", "text": "..." }],
  "isError": false
}
```

Every result lists its `sources` with their licence. File results come as `downloads`: each link builds its file when opened.

## Errors

A missing key answers `401`, an empty balance `402`, too many calls `429`. A call that fails or finds nothing is not counted. See [Errors and rate limits](https://terra-lab.ai/docs/errors).

## Description for agents

The text the server gives an agent to decide when to call this tool:

> Use this when the user wants to know what a public cloud GeoParquet holds before querying it: "what columns does the Fields of The World file have?", "which years does the FIRMS fire archive cover?". Give dataset: a portolan: id from find_datasets (open_registry), or the https URL of a GeoParquet file or of a hive-partitioned folder (.../year=*/x.parquet). Reads only the file footer, never the rows: row count, row groups, columns with type, min, max and null count, geometry column, CRS and bbox, compression, and for a partitioned dataset its partitions (keys and values). zone_queries says whether aggregate_dataset can count it per zone. Then aggregate_dataset counts or sums it per zone and extract_dataset cuts it to an area.


Source: https://terra-lab.ai/docs/api/inspect_dataset · Updated 2026-11-15