View/List Destinations

List All Destinations

Both Nexla API and Nexla CLI support methods to list all destinations in the authenticated user's account. A successful call returns detailed information like id, owner, type, credentials, activation status, and output configuration about all destinations.

API Endpoint

The primary endpoint for listing destinations is:

GET /data_sinks

Response Structure

The response includes comprehensive destination information including configuration details, credentials, and operational status.

Nexla API
Nexla CLI

List All Destinations: Request
GET /data_sinks

Example with curl:
curl https://api.nexla.io/data_sinks \
  -H "Authorization: Bearer <Access-Token>" \
  -H "Accept: application/vnd.nexla.api.v1+json"

List All Destinations: Request
nexla destination list

Response Examples

The API returns detailed destination objects with all configuration and metadata information.

Nexla API
Nexla CLI

List All Destinations: Response
[
  {
    "id": 5854,
    "owner": {
      "id": 2,
      "full_name": "Jeff Williams"
    },
    "org": {
      "id": 1,
      "name": "Nexla",
      "email_domain": "nexla.com",
      "email": null
    },
    "access_roles": ["owner"],
    "name": "Amazon S3 test",
    "description": "Customer data export to S3",
    "status": "ACTIVE",
    "data_set_id": 8092,
    "data_map_id": null,
    "sink_type": "s3",
    "sink_format": null,
    "sink_config": {
      "mapping": {
        "mode": "manual",
        "mapping": {
          "item_id": ["item_id"],
          "item_name": ["item_name"],
          "store_code": ["store_code"],
          "city_code": ["city_code"],
          "item_price": ["item_price"],
          "discount": ["discount"],
          "discounted_price": ["discounted_price"]
        },
        "fields_order": [
          "item_id",
          "item_name",
          "store_code",
          "city_code",
          "item_price",
          "discount",
          "discounted_price"
        ],
        "tracker_mode": "NONE"
      },
      "data_format": "csv",
      "sink_type": "s3",
      "path": "customer-solutions.nexla.com/echo/nexla_outputs",
      "output.dir.name.pattern": "{yyyy}-{MM}-{dd}/{HH}"
    },
    "sink_schedule": null,
    "managed": false,
    "nexset": {
      "id": 8092,
      "name": "echo"
    },
    "data_credentials": {
      "id": 5216,
      "name": "S3 Credentials",
      "credentials_type": "s3"
    },
    "updated_at": "2023-01-15T11:56:40.000Z",
    "created_at": "2023-01-15T11:56:40.000Z",
    "tags": []
  }
]

List All Destinations: Response
id        status        type         name        location                           credentials_name
------    ----------    -------     --------    -----------------------------      ------------------
5223      PAUSED        ftp          test        ftp://test-regression/sink         sftp_test
5224      ACTIVE        s3           test1       s3://test-nexla.com/sink           s3_test

Show One Destination

Fetch a specific destination accessible by the authenticated user. A successful call returns detailed information like id, owner, type, credentials, activation status, and output configuration about that destination.

API Endpoint

To retrieve a specific destination by its ID:

GET /data_sinks/{data_sink_id}

Nexla API

Show One Destination: Request
GET /data_sinks/5854

Basic Response

A successful call returns with status 200 and a JSON response containing the destination object:

Nexla API

Show One Destination: Basic Response
{
  "id": 5854,
  "owner": {
    "id": 82,
    "full_name": "John Doe"
  },
  "org": {
    "id": 1,
    "name": "Acme Corporation",
    "email_domain": "acme.com",
    "email": null
  },
  "access_roles": ["owner"],
  "name": "Amazon S3 test",
  "description": "Customer data export to S3",
  "status": "ACTIVE",
  "data_set_id": 8092,
  "data_map_id": null,
  "sink_type": "s3",
  "sink_format": null,
  "sink_config": {
    "mapping": {
      "mode": "manual",
      "mapping": {
        "item_id": ["item_id"],
        "item_name": ["item_name"],
        "store_code": ["store_code"],
        "city_code": ["city_code"],
        "item_price": ["item_price"],
        "discount": ["discount"],
        "discounted_price": ["discounted_price"]
      },
      "fields_order": [
        "item_id",
        "item_name",
        "store_code",
        "city_code",
        "item_price",
        "discount",
        "discounted_price"
      ],
      "tracker_mode": "NONE"
    },
    "data_format": "csv",
    "sink_type": "s3",
    "path": "customer-solutions.nexla.com/echo/nexla_outputs",
    "output.dir.name.pattern": "{yyyy}-{MM}-{dd}/{HH}"
  },
  "sink_schedule": null,
  "managed": false,
  "nexset": {
    "id": 8092,
    "name": "echo"
  },
  "data_credentials": {
    "id": 5216,
    "name": "S3 Credentials",
    "credentials_type": "s3"
  },
  "updated_at": "2023-01-15T11:56:40.000Z",
  "created_at": "2023-01-15T11:56:40.000Z",
  "tags": []
}

Expand Parameter

In case of Nexla API, add an expand query param with a truthy value to get more details about the destination. With this parameter, full details about the related resources (destination's Nexset, credentials, etc) will also be returned.

Expanded Response

When using the expand=1 parameter, the response includes comprehensive details about associated resources:

Nexla API

Show One Destination: Expanded Response
{
  "id": 5854,
  "owner": {
    "id": 82,
    "full_name": "John Doe",
    "email": "john.doe@acme.com"
  },
  "org": {
    "id": 1,
    "name": "Acme Corporation",
    "email_domain": "acme.com",
    "email": null
  },
  "access_roles": ["owner"],
  "name": "Amazon S3 test",
  "description": "Customer data export to S3",
  "status": "ACTIVE",
  "data_set_id": 8092,
  "data_map_id": null,
  "sink_type": "s3",
  "sink_format": null,
  "sink_config": {
    "mapping": {
      "mode": "manual",
      "mapping": {
        "item_id": ["item_id"],
        "item_name": ["item_name"],
        "store_code": ["store_code"],
        "city_code": ["city_code"],
        "item_price": ["item_price"],
        "discount": ["discount"],
        "discounted_price": ["discounted_price"]
      },
      "fields_order": [
        "item_id",
        "item_name",
        "store_code",
        "city_code",
        "item_price",
        "discount",
        "discounted_price"
      ],
      "tracker_mode": "NONE"
    },
    "data_format": "csv",
    "sink_type": "s3",
    "path": "customer-solutions.nexla.com/echo/nexla_outputs",
    "output.dir.name.pattern": "{yyyy}-{MM}-{dd}/{HH}"
  },
  "sink_schedule": null,
  "managed": false,
  "nexset": {
    "id": 8092,
    "name": "echo",
    "description": "Customer data processing pipeline",
    "output_schema": {
      "properties": {
        "city_code": {"type": "string", "format": "string"},
        "discount": {"format": "integer", "type": "string"},
        "discounted_price": {"type": "number", "format": "number"},
        "item_id": {"format": "integer", "type": "string"},
        "item_name": {"type": "string"},
        "item_price": {"format": "number", "type": "string"},
        "store_code": {"type": "string"}
      },
      "type": "object",
      "$schema": "http://json-schema.org/draft-04/schema#",
      "$schema-id": 1178328874
    },
    "status": "ACTIVE",
    "updated_at": "2023-01-15T14:11:36.000Z",
    "created_at": "2023-01-15T11:56:03.000Z",
    "version": 18350
  },
  "data_credentials": {
    "id": 5216,
    "name": "S3 Credentials",
    "description": "AWS S3 access credentials",
    "owner": {
      "id": 82,
      "full_name": "John Doe"
    },
    "org": {
      "id": 1,
      "name": "Acme Corporation",
      "email_domain": "acme.com"
    },
    "access_roles": ["owner"],
    "credentials_type": "s3",
    "credentials_version": "1",
    "managed": false,
    "credentials_non_secure_data": {
      "s3_auth_type": "Access Key"
    },
    "verified_status": "200 Ok",
    "verified_at": "2023-01-15T11:55:22.000Z",
    "updated_at": "2023-01-15T12:59:22.000Z",
    "created_at": "2023-01-14T15:07:59.000Z",
    "tags": []
  },
  "updated_at": "2023-01-15T11:56:40.000Z",
  "created_at": "2023-01-15T11:56:40.000Z",
  "tags": []
}

Nexla API
Nexla CLI

Show One Destination: Request
GET /data_sinks/{data_sink_id}

Example with expand parameter:
curl https://api.nexla.io/data_sinks/5854?expand=1 \
  -H "Authorization: Bearer <Access-Token>" \
  -H "Accept: application/vnd.nexla.api.v1+json"

Show One Destination: Request
nexla destination get <destination_id>

Destination Details Response

The expanded response includes comprehensive information about the destination and its associated resources.

Nexla API
Nexla CLI

Show One Destination: Response
{
  "id": 5854,
  "owner": {
    "id": 82,
    "full_name": "Jeff Williams"
  },
  "org": {
    "id": 1,
    "name": "Nexla",
    "email_domain": "nexla.com",
    "email": null
  },
  "access_roles": [
    "owner"
  ],
  "name": "Amazon S3 test",
  "description": "Customer data export to S3",
  "status": "ACTIVE",
  "data_set_id": 8092,
  "data_map_id": null,
  "sink_type": "s3",
  "sink_format": null,
  "sink_config": {
    "mapping": {
      "mode": "manual",
      "mapping": {
        "item_id": [
          "item_id"
        ],
        "item_name": [
          "item_name"
        ],
        "store_code": [
          "store_code"
        ],
        "city_code": [
          "city_code"
        ],
        "item_price": [
          "item_price"
        ],
        "discount": [
          "discount"
        ],
        "discounted_price": [
          "discounted_price"
        ]
      },
      "fields_order": [
        "item_id",
        "item_name",
        "store_code",
        "city_code",
        "item_price",
        "discount",
        "discounted_price"
      ],
      "tracker_mode": "NONE"
    },
    "data_format": "csv",
    "sink_type": "s3",
    "path": "customer-solutions.nexla.com/echo/nexla_outputs",
    "output.dir.name.pattern": "{yyyy}-{MM}-{dd}/{HH}"
  },
  "sink_schedule": null,
  "managed": false,
  "nexset": {
    "id": 8092,
    "name": "echo",
    "description": "Customer data processing pipeline"
  },
  "data_credentials": {
    "id": 5216,
    "name": "S3 Credentials",
    "credentials_type": "s3",
    "description": "AWS S3 access credentials"
  },
  "updated_at": "2023-01-15T11:56:40.000Z",
  "created_at": "2023-01-15T11:56:40.000Z",
  "tags": []
}

Show One Destination: Response
{
  "name": "test1",
  "data_credentials": "<5055:s3_test>",
  "sink_type": "s3",
  "data_set_id": 6024,
  "sink_config": {
    "poll_frequency": "Minute",
    "mapping": {
      "mode": "manual",
      "mapping": {
        "name": "name",
        "city": "city",
        "country": "country"
      }
    },
    "prefix": "test-nexla.com/sink",
    "data_format": "csv",
    "output.dir.name.pattern": "{yyyy}-{MM}-{dd}",
    "bucket": "/"
  },
  "description": "Test destination for customer data"
}

Filtering and Pagination

You can use query parameters to filter and paginate destination results:

Access Control Filtering

GET /data_sinks?access_roles=owner
GET /data_sinks?access_roles=admin,user

Pagination

GET /data_sinks?page=1&per_page=50

Response Field Details

The destination response includes comprehensive information about the destination and its configuration:

Basic Information

id: Unique identifier for the destination
name: Human-readable destination name
description: Optional description of the destination purpose
status: Current operational status (ACTIVE, PAUSED, ERROR, INACTIVE)
sink_type: Type of destination (s3, ftp, dropbox, data_map, etc.)
sink_format: Output data format (csv, json, parquet, etc.)

Configuration Details

sink_config: Complete destination configuration including:
- mapping: Field mapping configuration and field order
- data_format: Output data format specification
- path: Destination path or location
- output.dir.name.pattern: Directory naming pattern for outputs
sink_schedule: Output scheduling configuration
managed: Whether the destination is managed by Nexla

Relationships

data_set_id: ID of the associated Nexset providing data
data_map_id: ID of associated data map (if applicable)
nexset: Expanded Nexset information (when using expand parameter)
data_credentials: Associated credentials for destination access

Metadata

owner: User who owns the destination
org: Organization the destination belongs to
access_roles: User's access permissions for this destination
tags: Associated tags for organization
created_at: Creation timestamp
updated_at: Last modification timestamp

Additional Endpoint Capabilities

Beyond basic destination information, the API provides several additional endpoints for comprehensive destination management:

Configuration Validation

Validate destination configuration before activation:

POST /data_sinks/{data_sink_id}/config/validate

This endpoint validates the destination configuration and returns detailed error information if validation fails.

Quarantine Management

Access destination quarantine samples and offsets for error investigation:

# Get quarantine samples
POST /data_sinks/{data_sink_id}/probe/quarantine/sample

# Get quarantine offsets
GET /data_sinks/{data_sink_id}/quarantine/offset

# Get destination offsets
GET /data_sinks/{data_sink_id}/offset/{data_set_id}

Metrics and Monitoring

Access destination performance metrics and file statistics:

# Get destination metrics
GET /data_sinks/{data_sink_id}/metrics

# Get file statistics
GET /data_sinks/{data_sink_id}/metrics/files_stats

# Get file listing metrics
GET /data_sinks/{data_sink_id}/metrics/files

Integration with Data Flows

Destinations are connected to data flows through their associated Nexsets. The data_set_id field indicates which Nexset provides the data that gets written to this destination.

Best Practices

When listing destinations:

Use Expand Parameter: Include ?expand=1 to get complete resource details
Monitor Status: Check destination status to ensure operational health
Review Configurations: Verify sink configurations match your requirements
Check Credentials: Ensure associated credentials are valid and accessible
Track Changes: Monitor updated_at timestamps for recent modifications

After listing destinations, you may need to:

Update Destination

PUT /data_sinks/{destination_id}

Control Destination

PUT /data_sinks/{destination_id}/activate
PUT /data_sinks/{destination_id}/pause

Delete Destination

DELETE /data_sinks/{destination_id}

Monitor Performance

GET /data_sinks/{destination_id}/flow/metrics

List All Destinations​

API Endpoint​

Response Structure​

Response Examples​

Show One Destination​

API Endpoint​

Basic Response​

Expand Parameter​

Expanded Response​

Destination Details Response​

Filtering and Pagination​

Access Control Filtering​

Pagination​

Response Field Details​

Basic Information​

Configuration Details​

Relationships​

Metadata​

Additional Endpoint Capabilities​

Configuration Validation​

Quarantine Management​

Metrics and Monitoring​

Integration with Data Flows​

Best Practices​

Related Operations​

Update Destination​

Control Destination​

Delete Destination​

Monitor Performance​

List All Destinations

API Endpoint

Response Structure

Response Examples

Show One Destination

API Endpoint

Basic Response

Expand Parameter

Expanded Response

Destination Details Response

Filtering and Pagination

Access Control Filtering

Pagination

Response Field Details

Basic Information

Configuration Details

Relationships

Metadata

Additional Endpoint Capabilities

Configuration Validation

Quarantine Management

Metrics and Monitoring

Integration with Data Flows

Best Practices

Related Operations

Update Destination

Control Destination

Delete Destination

Monitor Performance