> ## 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 Import Sessions

> Retrieve a paginated list of import sessions with filtering by status, template, user, and expiration

# List Import Sessions

Retrieve a paginated list of import sessions for your organization. Use this endpoint to discover sessions that are in progress, find resumable sessions, or review completed imports.

<Note>
  By default, expired sessions are excluded from results. Pass `include_expired=true` to see sessions past their 24-hour TTL.
</Note>

## 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="status" type="string">
  Filter by session status.

  **Available values:** `created`, `parsed`, `mapped`, `validating`, `validated`, `submitting`, `submitted`, `failed`, `expired`

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

<ParamField query="template_id" type="string">
  Filter by import template identifier.

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

<ParamField query="user_id" type="string">
  Filter to sessions created by a specific user (UUID).

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

<ParamField query="include_expired" type="boolean" default="false">
  Include sessions past their `expires_at` timestamp. By default only active sessions are returned.
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number for pagination.

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

<ParamField query="size" type="integer" default="10">
  Number of items per page (1–100).

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

## Response

<ResponseField name="items" type="array[object]">
  Array of import session objects.

  <Expandable title="Import Session Object">
    <ResponseField name="id" type="string">
      Unique session identifier (UUID).
    </ResponseField>

    <ResponseField name="organization_id" type="string">
      Organization that owns this session.
    </ResponseField>

    <ResponseField name="user_id" type="string | null">
      User who created the session, if known.
    </ResponseField>

    <ResponseField name="template_id" type="string">
      Import template used (e.g. `logistics_requests`, `logistics_recharges`).
    </ResponseField>

    <ResponseField name="file_name" type="string">
      Original uploaded file name.
    </ResponseField>

    <ResponseField name="file_type" type="string">
      File format (`csv`, `xlsx`, `xls`).
    </ResponseField>

    <ResponseField name="status" type="string">
      Current session status.

      **Values:** `created`, `parsed`, `mapped`, `validating`, `validated`, `submitting`, `submitted`, `failed`, `expired`
    </ResponseField>

    <ResponseField name="numeric_locale" type="string | null">
      Numeric locale used for decimal parsing (e.g. `es_ES`).
    </ResponseField>

    <ResponseField name="actor_type" type="string">
      How the session was created.

      **Values:** `user`, `api_key`, `system`
    </ResponseField>

    <ResponseField name="actor_api_key_id" type="string | null">
      API key row ID, if created via API key.
    </ResponseField>

    <ResponseField name="total_rows" type="integer">
      Total number of rows parsed from the file.
    </ResponseField>

    <ResponseField name="valid_rows" type="integer">
      Number of rows that passed validation.
    </ResponseField>

    <ResponseField name="error_rows" type="integer">
      Number of rows with validation errors.
    </ResponseField>

    <ResponseField name="source_columns" type="array[string] | null">
      Detected column headers from the source file.
    </ResponseField>

    <ResponseField name="mapping" type="object | null">
      Column mapping from source to template columns.
    </ResponseField>

    <ResponseField name="errors_by_column" type="object | null">
      Error count per target column after validation.
    </ResponseField>

    <ResponseField name="submitted_file_id" type="string | null">
      File ID of the submitted artifact, after submission.
    </ResponseField>

    <ResponseField name="processing_job_id" type="string | null">
      Processing job ID, after submission.
    </ResponseField>

    <ResponseField name="project_id" type="string | null">
      Project scope, if provided at creation.
    </ResponseField>

    <ResponseField name="folder_id" type="string | null">
      Folder scope, if provided at creation.
    </ResponseField>

    <ResponseField name="selected_sheet" type="string | null">
      Selected sheet name for multi-sheet files.
    </ResponseField>

    <ResponseField name="detected_header_row" type="integer">
      Zero-based index of the detected header row.
    </ResponseField>

    <ResponseField name="expires_at" type="datetime | null">
      Session expiration timestamp (default 24 hours after creation).
    </ResponseField>

    <ResponseField name="created_at" type="datetime">
      When the session was created.
    </ResponseField>

    <ResponseField name="updated_at" type="datetime | null">
      When the session was last modified.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of sessions matching the filter.
</ResponseField>

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

<ResponseField name="size" type="integer">
  Number of items per page.
</ResponseField>

## Example

### List all active sessions

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X GET "https://api.dcycle.io/v2/imports/sessions?page=1&size=25" \
    -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/imports/sessions",
      headers={
          "x-api-key": os.environ["DCYCLE_API_KEY"],
          "x-organization-id": os.environ["DCYCLE_ORG_ID"],
      },
      params={"page": 1, "size": 25},
      timeout=30,
  )

  data = response.json()
  for session in data["items"]:
      print(f"{session['file_name']} — {session['status']} ({session['total_rows']} rows)")
  ```

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

  axios.get('https://api.dcycle.io/v2/imports/sessions', {
    headers: {
      'x-api-key': process.env.DCYCLE_API_KEY,
      'x-organization-id': process.env.DCYCLE_ORG_ID,
    },
    params: { page: 1, size: 25 },
  }).then((response) => {
    response.data.items.forEach((session) => {
      console.log(`${session.file_name} — ${session.status} (${session.total_rows} rows)`);
    });
  });
  ```
</CodeGroup>

### Filter by status and template

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X GET "https://api.dcycle.io/v2/imports/sessions?status=validated&template_id=logistics_requests" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"
```

### Successful Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "items": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "organization_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
      "user_id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
      "template_id": "logistics_requests",
      "file_name": "logistics_march.csv",
      "file_type": "csv",
      "status": "validated",
      "numeric_locale": "es_ES",
      "actor_type": "user",
      "actor_api_key_id": null,
      "total_rows": 240,
      "valid_rows": 238,
      "error_rows": 2,
      "source_columns": ["Trip Date", "Client", "Distance", "Origin", "Destination"],
      "mapping": {
        "trip_date": "Trip Date",
        "client": "Client",
        "distance_km": "Distance"
      },
      "errors_by_column": {"distance_km": 2},
      "status_detail": null,
      "submitted_file_id": null,
      "processing_job_id": null,
      "raw_file_id": null,
      "project_id": null,
      "folder_id": null,
      "selected_sheet": null,
      "detected_header_row": 0,
      "expires_at": "2026-04-09T14:00:00",
      "created_at": "2026-04-08T14:00:00",
      "updated_at": "2026-04-08T14:05:12"
    }
  ],
  "total": 1,
  "page": 1,
  "size": 25
}
```

## Typical Usage

### Session Resume Flow

The primary use case for this endpoint is session resume — finding an in-progress import session so the user can pick up where they left off:

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

headers = {
    "x-api-key": os.environ["DCYCLE_API_KEY"],
    "x-organization-id": os.environ["DCYCLE_ORG_ID"],
}

# Find resumable sessions for the current user
response = requests.get(
    "https://api.dcycle.io/v2/imports/sessions",
    headers=headers,
    params={
        "user_id": current_user_id,
        "status": "validated",
        "template_id": "logistics_requests",
    },
    timeout=30,
)

sessions = response.json()["items"]
if sessions:
    # Resume the most recent session
    session = sessions[0]
    print(f"Resuming session {session['id']} — {session['file_name']}")
```

## Common Errors

### 401 Unauthorized

**Cause:** Missing or invalid API key

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

**Solution:** Verify your API key is valid and active. Get a new one from [Settings -> API](https://app.dcycle.io/settings/api).

### 422 Validation Error

**Cause:** Invalid query parameter value (e.g. unrecognized status)

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": [
    {
      "loc": ["query", "status"],
      "msg": "value is not a valid enumeration member",
      "type": "type_error.enum"
    }
  ]
}
```

**Solution:** Check that filter values match the available enum values listed above.

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Create Import Session" icon="plus" href="/api-reference/imports/overview#1-create-the-session">
    Upload a file and start a new import session
  </Card>

  <Card title="Get Session Status" icon="magnifying-glass" href="/api-reference/imports/overview#7-check-status">
    Check the status of a specific import session
  </Card>

  <Card title="Get Provider Options" icon="list" href="/api-reference/imports/get-options-source">
    Resolve template option sources into selectable values
  </Card>

  <Card title="Imports Overview" icon="book" href="/api-reference/imports/overview">
    Full end-to-end import workflow guide
  </Card>
</CardGroup>