> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poddata.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# A target's folder

> Everything PodData holds for a target and its confirmed rivals, as files: the index, each file and its columns, the zip, and what's held back.

A target's folder is everything PodData holds tied to one of your team's targets, as files: a part for each company, the target first, then each confirmed rival, its listed parent and its comparables.

## 1. Read the index

```bash theme={null}
curl -s https://api.poddata.ai/v1/targets/northwind-dental/folder -H "Authorization: Bearer $PODDATA_API_KEY"
```

Each part has its `role` (`target`, `rival`, `parent` or `comparable`) and its `company`, and lists its `sources`. For each source:

* `records` and `signals`: one entry a kind, each with its `count`, its first and last day (`from`, `to`), `file`, the CSV's address, and `rows`, the same rows as JSON. Where `file` is null, `held` says why.
* `documents`: how many, and the first and last day filed.
* `pages`, for the company's own site: the pages read, with their file.

For the target, the index adds:

* `quotes`: two files, what its people said (`said`) and what others said of it (`named`).
* `licensed`: the figures your team's own data licences read, by vendor, as JSON.
* `reports`: your team's reports on it, each with its JSON address (`rows`) and its zip (`file`).
* `not_held`: every source that holds nothing for it, with where it stands and why.
* `download`: the address of the zip.

The MCP tool `target_folder` gives the same index.

## 2. Fetch each file

Fetch each `file` by its own address, with the key. A file holds one source and one kind. A file longer than one answer holds stops at its row limit, says so in its last row, and gives the cursor for the rest in the `X-PodData-Next` header: ask again with `cursor` set to it.

```bash theme={null}
curl -s -D headers.txt 'https://api.poddata.ai/v1/companies/northwind-dental/records?source=nppes-npi&kind=organization&format=csv' \
  -H "Authorization: Bearer $PODDATA_API_KEY" -o northwind-dental-nppes-npi-organization.csv
```

Most review and retail platforms' reviews come as a file. Where one is held back until its terms allow handing it on, `file` is null and `held` says why: read its `rows` as JSON, a page at a time, and save them as JSON.

## 3. Or take the zip

```bash theme={null}
curl -s 'https://api.poddata.ai/v1/targets/northwind-dental/folder?format=zip' \
  -H "Authorization: Bearer $PODDATA_API_KEY" -o northwind-dental-folder.zip
```

It holds the folder's files, a part a folder, with `index.json`, `coverage.csv` and a `README.txt` that lists each file with its address, and what it leaves out and why. A file that would take it past its row limit is left out, and the README gives its address. PodData's own copies of originals aren't in it: each is read on its own with `GET /documents/{id}`, under the key's daily limit.

The diligence skill's puller fetches the index and every file in one command: see [A diligence, start to end](https://docs.poddata.ai/diligence.md).

## Each file's columns

A file is at most 10,000 rows; the zip holds at most 100,000 in all.

### A source's records

| Column | What it holds |
| - | - |
| `record_id` | The record’s id, for `GET /records/{id}` |
| `source` | The source it was read from, by its id in PodData’s catalog |
| `kind` | Its kind, as the source has it: a registration, a licence, a review, a listing |
| `day` | Its own day, YYYY-MM-DD: when it happened or was posted, never when PodData read it |
| `title` | Its title |
| `text` | At most 80 words of its own text |
| `url` | Its page on the source’s own site |
| `revisions` | How many times it has changed since PodData first read it |
| `link` | The confirmed link that ties it to the company |
| `read` | The day PodData last read it |

Then a column for each of the records' own fields, by its name: a registration's `npi`, a licence's `expires`.

### A source's signals

| Column | What it holds |
| - | - |
| `signal_id` | The signal’s id, for `GET /signals/{id}` |
| `source` | The source it was read from, by its id in PodData’s catalog |
| `kind` | Its kind, as the source has it: a registration, a licence, a review, a listing |
| `day` | Its own day, YYYY-MM-DD: when it happened or was posted, never when PodData read it |
| `rating` | Its stars, for a review |
| `excerpt` | At most 80 words of its own text |
| `url` | Its page on the source’s own site |
| `read` | The day PodData last read it |
| `sort` | The order the pull read the platform in |
| `filter` | What the pull asked the platform for |
| `method` | How the pull read it |
| `platform_total` | The platform’s own count when it was read |
| `platform_rating` | The platform’s own rating when it was read |

Then a column for each of the signals' own counts.

### A company's documents

| Column | What it holds |
| - | - |
| `document_id` | The document’s id, for `GET /documents/{id}` |
| `company` | The company it’s from |
| `title` | Its title |
| `type` | Its type, such as an annual report or a press release |
| `form` | Its form, for a filing: 10-K, 8-K |
| `filed` | The day it was filed or published |
| `period_end` | The last day of the period it reports on |
| `pages` | How many pages it has |
| `source` | The source it was read from, by its id in PodData’s catalog |
| `original` | The original’s address, where the company or the regulator keeps it |
| `filing` | The filing it belongs to, on EDGAR |
| `shown` | How much of it the key may read: `whole` or `passages` |
| `document` | PodData’s address for it, `GET /documents/{id}` |

Every cell keeps to the rule of the rest of the API: at most 80 words in a row from a source, and no reviewer's or poster's name, since none is held.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.