> ## 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.

# List File Readings

> Retrieve extracted file readings produced by the asynchronous document processing pipeline

# List File Readings

Use this endpoint after uploading and confirming a file to retrieve the parsed reading payload generated by the file
processing pipeline.

This is the entry point for programmatic post-upload automation:

1. Upload file
2. Wait for async classification and processing
3. Fetch extracted readings
4. Optionally edit the reading
5. Create linked invoices or wastes from the reading

## Request

### Headers

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication

  **Example:** `sk_live_1234567890abcdef`
</ParamField>

<ParamField header="x-organization-id" type="string" required>
  Your organization UUID

  **Example:** `a8315ef3-dd50-43f8-b7ce-d839e68d51fa`
</ParamField>

### Query Parameters

<ParamField query="file_id" type="string[]">
  Optional file UUID list. When provided, the endpoint returns readings for those files instead of folder-style browsing.
</ParamField>

<ParamField query="folder_id" type="string">
  Optional folder UUID to browse readings within a folder.
</ParamField>

<ParamField query="project_id" type="string">
  Optional project UUID to filter readings to a project.
</ParamField>

<ParamField query="linked" type="boolean">
  Filter by whether the file already has linked invoices or wastes.
</ParamField>

<ParamField query="name" type="string">
  Case-insensitive file name search.
</ParamField>

<ParamField query="category" type="string[]">
  Optional reading categories. Values come from the file reading categories returned by the API, such as
  `water`, `electricity`, `gas`, `fuel_delivery`, `recharges`, or `wastes`.
</ParamField>

<ParamField query="page" type="integer">
  Page number for folder-style browsing. Defaults to `1`.
</ParamField>

<ParamField query="size" type="integer">
  Page size for folder-style browsing.
</ParamField>

## Response

Returns a paginated list of file reading items (HTTP 200).

<ResponseField name="items" type="array[object]">
  List of file reading entries.

  <Expandable title="File Reading Item">
    <ResponseField name="id" type="string">
      File UUID.
    </ResponseField>

    <ResponseField name="name" type="string">
      Original file name (without extension).
    </ResponseField>

    <ResponseField name="extension" type="string">
      File extension (e.g. `"pdf"`, `"xlsx"`).
    </ResponseField>

    <ResponseField name="mime_type" type="string">
      MIME type of the uploaded file.
    </ResponseField>

    <ResponseField name="size_kb" type="number">
      File size in kilobytes.
    </ResponseField>

    <ResponseField name="folder_id" type="string | null">
      Folder UUID if the file is in a folder.
    </ResponseField>

    <ResponseField name="status" type="string">
      File upload status (e.g. `"uploaded"`).
    </ResponseField>

    <ResponseField name="url" type="string">
      Presigned download URL for the file.
    </ResponseField>

    <ResponseField name="tags" type="array[string]">
      Classifier tags (e.g. `["invoice", "water"]`).
    </ResponseField>

    <ResponseField name="category" type="string">
      Derived category: `water`, `electricity`, `gas`, `fuel_delivery`, `recharges`, or `wastes`.
    </ResponseField>

    <ResponseField name="linked" type="boolean">
      `true` if invoices or wastes have already been created from this file.
    </ResponseField>

    <ResponseField name="reading" type="object | null">
      Parsed reading data. `null` if processing has not completed.

      <Expandable title="Reading Object">
        <ResponseField name="id" type="string">
          File reading UUID.
        </ResponseField>

        <ResponseField name="status" type="string">
          Processing status: `success` or `error`.
        </ResponseField>

        <ResponseField name="content" type="object">
          Extracted content from OCR or LLM processing.

          <Expandable title="Content Object">
            <ResponseField name="items" type="array[object]">
              Extracted line items. Shape varies by category (e.g. invoice fields for energy, waste fields for wastes).
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of matching items.
</ResponseField>

<ResponseField name="page" type="integer">
  Current page number.
</ResponseField>

<ResponseField name="size" type="integer">
  Page size.
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X GET "https://api.dcycle.io/v1/files/readings?file_id=11111111-1111-1111-1111-111111111111" \
    -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/v1/files/readings",
      headers={
          "x-api-key": os.environ["DCYCLE_API_KEY"],
          "x-organization-id": os.environ["DCYCLE_ORG_ID"],
      },
      params={
          "file_id": ["11111111-1111-1111-1111-111111111111"],
      },
      timeout=30,
  )

  payload = response.json()
  print(payload["items"][0]["reading"]["content"]["items"])
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const axios = require('axios');

  axios.get('https://api.dcycle.io/v1/files/readings', {
    headers: {
      'x-api-key': process.env.DCYCLE_API_KEY,
      'x-organization-id': process.env.DCYCLE_ORG_ID,
    },
    params: {
      file_id: '11111111-1111-1111-1111-111111111111',
    },
  }).then(response => {
    const items = response.data.items[0].reading.content.items;
    console.log(items);
  });
  ```
</CodeGroup>

### Successful Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "items": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "name": "invoice_march",
      "extension": "pdf",
      "mime_type": "application/pdf",
      "size_kb": 248,
      "folder_id": null,
      "status": "uploaded",
      "url": "https://...",
      "tags": ["invoice", "water"],
      "category": "water",
      "linked": false,
      "reading": {
        "id": "22222222-2222-2222-2222-222222222222",
        "status": "success",
        "content": {
          "items": [
            {
              "invoice_number": "WTR-2024-03",
              "quantity": 32.1,
              "unit": "cubic_metre_(m3)",
              "start_date": "2024-03-01",
              "end_date": "2024-03-31"
            }
          ]
        }
      }
    }
  ],
  "total": 1,
  "page": 1,
  "size": 1
}
```

## Common Errors

### 401 Unauthorized

**Cause:** Missing or invalid API key

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"detail": "Invalid API key for organization", "code": "INVALID_API_KEY"}
```

### 403 Forbidden

**Cause:** The authenticated user is not a member of the organization

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"detail": "Logged User is not Member of Organization", "code": "LOGGED_USER_NOT_MEMBER"}
```

## Notes

* This endpoint does not trigger processing. It only returns the current reading state.
* `linked=true` means downstream invoices or wastes already exist for the file.
* When `file_id` is provided, the response is effectively a direct fetch for those file readings.

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Upload Files" icon="upload" href="/api-reference/files/upload">
    Upload files via presigned S3 URLs
  </Card>

  <Card title="Update Reading" icon="pencil" href="/api-reference/files/update-reading">
    Edit extracted content before creating records
  </Card>

  <Card title="Create Records" icon="plus" href="/api-reference/files/create-records">
    Convert readings into invoices or wastes
  </Card>

  <Card title="Retry Processing" icon="rotate" href="/api-reference/files/process">
    Re-queue a stalled file for processing
  </Card>
</CardGroup>