List Import Sessions

const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

fetch('https://api.dcycle.io/v2/imports/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v2/imports/sessions"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

{
  "items": {
    "id": "<string>",
    "organization_id": "<string>",
    "user_id": {},
    "template_id": "<string>",
    "file_name": "<string>",
    "file_type": "<string>",
    "status": "<string>",
    "numeric_locale": {},
    "actor_type": "<string>",
    "actor_api_key_id": {},
    "total_rows": 123,
    "valid_rows": 123,
    "error_rows": 123,
    "source_columns": {},
    "mapping": {},
    "errors_by_column": {},
    "submitted_file_id": {},
    "processing_job_id": {},
    "project_id": {},
    "folder_id": {},
    "selected_sheet": {},
    "detected_header_row": 123,
    "expires_at": {},
    "created_at": {},
    "updated_at": {}
  },
  "total": 123,
  "page": 123,
  "size": 123
}

GET

imports

sessions

List Import Sessions

const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

fetch('https://api.dcycle.io/v2/imports/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v2/imports/sessions"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

{
  "items": {
    "id": "<string>",
    "organization_id": "<string>",
    "user_id": {},
    "template_id": "<string>",
    "file_name": "<string>",
    "file_type": "<string>",
    "status": "<string>",
    "numeric_locale": {},
    "actor_type": "<string>",
    "actor_api_key_id": {},
    "total_rows": 123,
    "valid_rows": 123,
    "error_rows": 123,
    "source_columns": {},
    "mapping": {},
    "errors_by_column": {},
    "submitted_file_id": {},
    "processing_job_id": {},
    "project_id": {},
    "folder_id": {},
    "selected_sheet": {},
    "detected_header_row": 123,
    "expires_at": {},
    "created_at": {},
    "updated_at": {}
  },
  "total": 123,
  "page": 123,
  "size": 123
}

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.

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

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Query Parameters

string

Filter by session status.Available values: created, parsed, mapped, validating, validated, submitting, submitted, failed, expiredExample: validated

string

Filter by import template identifier.Example: logistics_requests

string

Filter to sessions created by a specific user (UUID).Example: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

boolean

default:"false"

Include sessions past their expires_at timestamp. By default only active sessions are returned.

integer

default:"1"

Page number for pagination.Example: 2

integer

default:"10"

Number of items per page (1–100).Example: 25

Response

array[object]

Array of import session objects.

Show Import Session Object

string

Unique session identifier (UUID).

string

Organization that owns this session.

string | null

User who created the session, if known.

string

Import template used (e.g. logistics_requests, logistics_recharges).

string

Original uploaded file name.

string

File format (csv, xlsx, xls).

string

Current session status.Values: created, parsed, mapped, validating, validated, submitting, submitted, failed, expired

string | null

Numeric locale used for decimal parsing (e.g. es_ES).

string

How the session was created.Values: user, api_key, system

string | null

API key row ID, if created via API key.

integer

Total number of rows parsed from the file.

integer

Number of rows that passed validation.

integer

Number of rows with validation errors.

array[string] | null

Detected column headers from the source file.

object | null

Column mapping from source to template columns.

object | null

Error count per target column after validation.

string | null

File ID of the submitted artifact, after submission.

string | null

Processing job ID, after submission.

string | null

Project scope, if provided at creation.

string | null

Folder scope, if provided at creation.

string | null

Selected sheet name for multi-sheet files.

integer

Zero-based index of the detected header row.

datetime | null

Session expiration timestamp (default 24 hours after creation).

datetime

When the session was created.

datetime | null

When the session was last modified.

integer

Total number of sessions matching the filter.

integer

Current page number.

integer

Number of items per page.

Example

List all active sessions

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}"

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)")

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)`);
  });
});

Filter by status and template

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

{
  "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:

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

{
  "detail": "Invalid API key",
  "code": "INVALID_API_KEY"
}

Solution: Verify your API key is valid and active. Get a new one from Settings -> API.

422 Validation Error

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

{
  "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.

Create Import Session

Upload a file and start a new import session

Get Session Status

Check the status of a specific import session

Get Provider Options

Resolve template option sources into selectable values

Imports Overview

Full end-to-end import workflow guide

​List Import Sessions

​Request

​Headers

​Query Parameters

​Response

​Example

​List all active sessions

​Filter by status and template

​Successful Response

​Typical Usage

​Session Resume Flow

​Common Errors

​401 Unauthorized

​422 Validation Error

​Related Endpoints

Create Import Session

Get Session Status

Get Provider Options

Imports Overview

List Import Sessions

Request

Headers

Query Parameters

Response

Example

List all active sessions

Filter by status and template

Successful Response

Typical Usage

Session Resume Flow

Common Errors

401 Unauthorized

422 Validation Error

Related Endpoints