Skip to main content
GET
/
v2
/
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));
{
  "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,
  "pages": 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

​
x-api-key
string
required
Your API key for authentication.
​
x-organization-id
string
required
Your organization UUID.

​
Query Parameters

​
status
string
Filter by session status.Available values: created, parsed, mapped, validating, validated, submitting, submitted, failed, expiredExample: validated
​
template_id
string
Filter by import template identifier.Example: logistics_requests
​
user_id
string
Filter to sessions created by a specific user (UUID).Example: a8315ef3-dd50-43f8-b7ce-d839e68d51fa
​
include_expired
boolean
default:"false"
Include sessions past their expires_at timestamp. By default only active sessions are returned.
​
page
integer
default:"1"
Page number for pagination.Example: 2
​
size
integer
default:"10"
Number of items per page (1–100).Example: 25

​
Response

​
items
array[object]
Array of import session objects.
​
total
integer
Total number of sessions matching the filter.
​
page
integer
Current page number.
​
size
integer
Number of items per page.
​
pages
integer
Total number of pages.

​
Examples

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

​
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,
  "pages": 1
}

​
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