Skip to main content
Version: Next

DatasetClient <Data>

Client for managing a specific Dataset.

Datasets store structured data results from Actor runs. This client provides methods to push items, list and retrieve items, download items in various formats (JSON, CSV, Excel, etc.), and manage the dataset.

@example
const client = new ApifyClient({ token: 'my-token' });
const datasetClient = client.dataset('my-dataset-id');

// Push items to the dataset
await datasetClient.pushItems([
  { url: 'https://example.com', title: 'Example' },
  { url: 'https://test.com', title: 'Test' }
]);

// List all items
const { items } = await datasetClient.listItems();

// Download items as CSV
const buffer = await datasetClient.downloadItems('csv');
@see

https://docs.apify.com/platform/storage/dataset

Hierarchy

  • ResourceClient
    • DatasetClient

Index

Properties

Methods

Properties

inheritedapifyClient

apifyClient: ApifyClient

inheritedbaseUrl

baseUrl: string

inheritedhttpClient

httpClient: HttpClient

optionalinheritedid

id?: string

optionalinheritedparams

params?: Record<string, unknown>

inheritedpublicBaseUrl

publicBaseUrl: string

inheritedresourcePath

resourcePath: string

optionalinheritedsafeId

safeId?: string

inheritedurl

url: string

Methods

createItemsPublicUrl

  • createItemsPublicUrl(options): Promise<string>

  • Generates a public URL for accessing dataset items.

    If the client has permission to access the dataset's URL signing key, the URL will include a cryptographic signature allowing access without authentication. This is useful for sharing dataset results with external services or users.

    @example
    // Create a URL that expires in 1 hour with specific fields
    const url = await client.dataset('my-dataset').createItemsPublicUrl({
      expiresInSecs: 3600,
      fields: ['url', 'title'],
      limit: 100
    });
    console.log(`Share this URL: ${url}`);

    // Create a permanent public URL for clean items only
    const url = await client.dataset('my-dataset').createItemsPublicUrl({
      clean: true,
      skipEmpty: true
    });

    Parameters

    Returns Promise<string>

    A public URL string for accessing the dataset items

delete

  • delete(): Promise<void>

downloadItems

  • downloadItems(format, options): Promise<Buffer>

  • Downloads dataset items in a specific format.

    Unlike listItems which returns a PaginatedList with an array of individual dataset items, this method returns the items serialized to the provided format (JSON, CSV, Excel, etc.) as a Buffer. Useful for exporting data for further processing.

    @see

    https://docs.apify.com/api/v2/dataset-items-get

    @example
    // Download as CSV with BOM for Excel compatibility
    const csvBuffer = await client.dataset('my-dataset').downloadItems('csv', { bom: true });
    require('fs').writeFileSync('output.csv', csvBuffer);

    // Download as Excel with custom options
    const xlsxBuffer = await client.dataset('my-dataset').downloadItems('xlsx', {
      fields: ['url', 'title', 'price'],
      skipEmpty: true,
      limit: 1000
    });

    // Download as XML with custom element names
    const xmlBuffer = await client.dataset('my-dataset').downloadItems('xml', {
      xmlRoot: 'products',
      xmlRow: 'product'
    });

    Parameters

    Returns Promise<Buffer>

    Buffer containing the serialized data in the specified format

get

  • get(): Promise<undefined | Dataset>

getStatistics

listItems

  • listItems(options): PaginatedIterator<Data>

  • Lists items in the dataset.

    Returns a paginated list of dataset items. You can use pagination parameters to retrieve specific subsets of items, and various filtering and formatting options to customize the output.

    @see

    https://docs.apify.com/api/v2/dataset-items-get

    @example
    // Get first 100 items
    const { items, total } = await client.dataset('my-dataset').listItems({ limit: 100 });
    console.log(`Retrieved ${items.length} of ${total} total items`);

    // Get items with specific fields only
    const { items } = await client.dataset('my-dataset').listItems({
      fields: ['url', 'title'],
      skipEmpty: true,
      limit: 50
    });

    // Get items in descending order with pagination
    const { items } = await client.dataset('my-dataset').listItems({
      desc: true,
      offset: 100,
      limit: 50
    });

    Parameters

    Returns PaginatedIterator<Data>

    A paginated list with items, total count, offset, count, and limit

pushItems

  • pushItems(items): Promise<void>

  • Stores one or more items into the dataset.

    Items can be objects, strings, or arrays thereof. Each item will be stored as a separate record in the dataset. Objects are automatically serialized to JSON. If you provide an array, all items will be stored in order. This method is idempotent - calling it multiple times with the same data will not create duplicates, but will append items each time.

    @see

    https://docs.apify.com/api/v2/dataset-items-post

    @example
    // Store a single object
    await client.dataset('my-dataset').pushItems({
      url: 'https://example.com',
      title: 'Example Page',
      extractedAt: new Date()
    });

    // Store multiple items at once
    await client.dataset('my-dataset').pushItems([
      { url: 'https://example.com', title: 'Example' },
      { url: 'https://test.com', title: 'Test' },
      { url: 'https://demo.com', title: 'Demo' }
    ]);

    // Store string items
    await client.dataset('my-dataset').pushItems(['item1', 'item2', 'item3']);

    Parameters

    • items: string | Data | string[] | Data[]

      A single item (object or string) or an array of items to store. Objects are automatically stringified to JSON. Strings are stored as-is.

    Returns Promise<void>

update

  • update(newFields): Promise<Dataset>
Page Options