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

# Get a File (v2)

> A file's state: its classification, its template and its automatic import

[← Files](https://code.dcycle.io/api-reference/files/overview.md)

Read how a file goes after [uploading it](https://code.dcycle.io/api-reference/files/upload-v2.md). A file of another organization, or in the
trash, answers the same `404` as one that does not exist. Instead of polling a spreadsheet you uploaded with an API key,
subscribe a [webhook endpoint](https://code.dcycle.io/api-reference/webhooks/overview.md#file-events) to `file.finished`: it brings this same
answer each time the file stops.

> [!WARNING]
>
> **Beta.** Part of the Import API, in beta. The contract may still change before general availability.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.dcycle.io/v2/files/6f1e2d3c-4b5a-4978-8c6d-5e4f3a2b1c0d" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os

import requests

response = requests.get(
    "https://api.dcycle.io/v2/files/6f1e2d3c-4b5a-4978-8c6d-5e4f3a2b1c0d",
    headers={"x-api-key": os.environ["DCYCLE_API_KEY"], "x-organization-id": os.environ["DCYCLE_ORG_ID"]},
)
print(response.json()["auto_import"])
```

```json 200 theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "6f1e2d3c-4b5a-4978-8c6d-5e4f3a2b1c0d",
  "name": "residuos-enero",
  "extension": "xlsx",
  "mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
  "size_kb": 84,
  "status": "needs_review",
  "step": "awaiting_mapping",
  "reason": null,
  "actions": ["map_columns"],
  "review_url": "https://app.dcycle.io/acme/a8315ef3-dd50-43f8-b7ce-d839e68d51fa/data/files/upload?run=tabular:6f1e2d3c-4b5a-4978-8c6d-5e4f3a2b1c0d&run_file=6f1e2d3c-4b5a-4978-8c6d-5e4f3a2b1c0d",
  "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
  "folder_id": null,
  "facility_id": "9b2e4c1a-6d3f-4e8b-a7c5-1f0d2e3b4a59",
  "transport_direction": null,
  "project_id": null,
  "classifications": [{ "document_type": "document::wastes", "confidence": 0.9 }],
  "template_id": "wastes",
  "duplicate": null,
  "auto_import": {
    "state": "held",
    "reason": "validation_errors",
    "step": "validate",
    "import_id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f"
  },
  "created_at": "2026-11-05T17:20:04Z",
  "updated_at": "2026-11-05T17:20:09Z"
}
```

## Request

### Path Parameters

**file\_id** `string` *required*

The file's id, from [`POST /v2/files`](https://code.dcycle.io/api-reference/files/upload-v2) or the [presigned flow](https://code.dcycle.io/api-reference/files/upload.md).

### Headers

**x-api-key** `string` *required*

Your API key.

**x-organization-id** `string` *required*

The organization that owns the file.

## Response

**status** `string`

What to branch on. Poll while it is `processing`, or wait for the `file.finished` webhook.

| `status` | Meaning | `step` |
| - | - | - |
| `processing` | Dcycle is working on it | `uploading`, `classifying`, `processing`, `calculating` |
| `needs_review` | Someone has to act: see `actions` and `review_url` | `awaiting_duplicate_review`, `awaiting_classification_confirmation`, `awaiting_mapping`, `awaiting_dataset_import`, `awaiting_review`, `not_calculated` |
| `completed` | Nothing is left to do | `completed`, `completed_with_errors`, and `not_processed` when you asked for `skip_processing` or it went in an evidence folder |
| `failed` | It stopped: see `reason` | `error`, `upload_limit_reached`, and `not_processed` in any other case: the file is stored, but nothing was read from it |

**step** `string`

The real step behind `status`, for more detail. New values may appear: branch on `status`.

**reason** `object`

Why it failed, or what went wrong in part: `code`, `message` (for people; do not parse it) and `retryable`. `NOT_PROCESSED`
and `UPLOAD_LIMIT_REACHED` are not retryable. Null otherwise.

**actions** `array`

What can be done with it now, as stable identifiers such as `map_columns`. Empty when there is nothing to do.

**review\_url** `string`

Where a person reviews it in the Dcycle app: the file in the upload flow or, for an organization that does not have
that flow yet, My files. Only when it `needs_review`.

**classifications** `array`

Empty until it is classified; one per service found in the file, each with `document_type` and `confidence` (0 to 1,
and 1 for a person's confirmation).

**template\_id** `string`

The import template its classification leads straight to. Null when there is none: then
[open the session](https://code.dcycle.io/api-reference/files/import-sessions-v2.md) with the template you choose.

**duplicate** `object`

Set while the file is held back because its bytes match another file of the organization: its `status` is
`needs_review` until someone decides. Has `status` (`suspected`) and `duplicate_of_file_id`.

**auto\_import** `object`

Where the automatic import of a spreadsheet stands. Null when it did not run for this file: that is every file while
the feature is not on for your organization. A spreadsheet's job starts after its classification, so this can be null
for some seconds after `classifications` fills.

**fields**

**state** `string`

`running`: queued or running. `imported`: its submit was accepted, and the rows are being saved. `held`: it
stopped at the first problem and left the session as it was, for a person to continue. `failed`: it could not finish.

**reason** `string`

Why it was `held`: a short machine-readable reason, such as `validation_errors`, `validation_ambiguous`,
`too_large`, `unreadable`, `already_submitted` or `missing_context:facility_id`. Null otherwise.

**step** `string`

The last step it reached, such as `ensure`, `suggest`, `mapping`, `unique_values`, `validate` or `submit`. Null while
it is `running`. For information: do not branch on it.

**import\_id** `string`

The import session it worked on, if it opened one. Continue from it with the [importer's routes](https://code.dcycle.io/api-reference/imports/overview.md).

> [!NOTE]
>
> The answer carries no download URL. A file's bytes are read with [`GET /v1/files/{file_id}`](https://code.dcycle.io/api-reference/files/overview).

## Errors

Errors are [problem details](https://code.dcycle.io/api-reference/errors.md). `404 NOT_FOUND`, `422 REQUEST_VALIDATION_FAILED` (an id that is not
a UUID), and `429` beyond the [rate limits](https://code.dcycle.io/api-reference/rate-limits.md).

## Related Endpoints

> [card] [Upload a File (v2)](https://code.dcycle.io/api-reference/files/upload-v2.md)
>
> Upload one file in one call

> [card] [Get a File's Sheets](https://code.dcycle.io/api-reference/files/sheets-v2.md)
>
> The tabs of a workbook

> [card] [Open an Import Session](https://code.dcycle.io/api-reference/files/import-sessions-v2.md)
>
> Import a spreadsheet you uploaded


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