# Dataset Classifier (`lukas.priban/dataset-classifier`) Actor Automatically classify rows in any Apify dataset into categories you define. Point it at a dataset, pick a text column, provide your categories, and get back the original data with a new classification column added. - **URL**: https://apify.com/lukas.priban/dataset-classifier.md - **Developed by:** [Lukas Priban](https://apify.com/lukas.priban) (community) - **Categories:** Other - **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing Pay per usage This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Dataset Classifier Automatically classify rows in any Apify dataset into categories you define. Point it at a dataset, pick a text column, provide your categories, and get back the original data with a new classification column added. ### What it does 1. Reads rows from an Apify dataset or a CSV file you upload 2. Classifies each row's text field into one (or more) of your categories 3. Outputs the original rows with an added `_classification` field No setup, no API keys, no configuration beyond the basics. Just provide your data and categories. ### Use cases - **Categorize scraped articles** — Sort news articles into Technology, Business, Sports, etc. - **Tag product listings** — Classify products by type, audience, or price tier - **Filter leads** — Separate B2B from B2C leads based on company descriptions - **Sort reviews by topic** — Classify customer feedback into Product, Shipping, Support, etc. - **Organize job postings** — Tag jobs by seniority, department, or work model ### Input | Field | Type | Required | Description | |---|---|---|---| | **Source Dataset** | string | No* | Apify dataset to classify (use picker or paste ID) | | **CSV File** | string | No* | Upload a CSV file to classify | | **Field to Classify** | string | Yes | Name of the text column (e.g. `description`, `title`) | | **Categories** | string[] | Yes | List of target categories | | **Category Descriptions** | object | No | Descriptions to help disambiguate similar categories | | **Context Fields** | string[] | No | Extra columns to provide as context alongside the main field | | **Output Field Name** | string | No | Name of the new column (default: `_classification`) | | **Allow Multiple Categories** | boolean | No | Assign multiple categories per row (default: `false`) | | **Max Items** | integer | No | Limit how many rows to process | | **LLM Model** | string | No | Override the default model (`openai/gpt-4o-mini`). See [openrouter.ai/models](https://openrouter.ai/models). | | **Suggest Categories From Sample** | boolean | No | If enabled, skip classification and have the LLM propose categories from a sample of your data. See "Suggest mode" below. | | **Sample Size For Category Suggestion** | integer | No | Rows to sample when suggesting categories (default 30, range 5–100). | | **Allow UNCATEGORIZED** | boolean | No | Let the model use `"UNCATEGORIZED"` when no listed category fits. Default off (model forced to pick). | | **Suggest New Categories From UNCATEGORIZED** | boolean | No | After classification, sample UNCATEGORIZED rows and propose new categories that would cover them. Requires **Allow UNCATEGORIZED**. | *Provide either **Source Dataset** or **CSV File**, not both. #### Example input (dataset) ```json { "datasetId": "abc123DEF456", "classifyField": "title", "categories": ["Technology", "Business", "Entertainment", "Sports", "Science"] } ```` #### Example input (CSV) ```json { "csvFile": "title,description\nApple Vision Pro,Apple launches mixed reality headset\nSuper Bowl,Chiefs win in overtime", "classifyField": "description", "categories": ["Technology", "Sports", "Business"] } ``` #### Using category descriptions When categories are ambiguous or overlap, add descriptions to improve accuracy: ```json { "datasetId": "abc123DEF456", "classifyField": "description", "categories": ["B2B", "B2C", "Internal"], "categoryDescriptions": { "B2B": "Business-to-business products and services sold to companies", "B2C": "Consumer products and services sold to individuals", "Internal": "Internal tools, documentation, and employee-facing resources" } } ``` #### Using context fields Provide additional columns for more accurate classification: ```json { "datasetId": "abc123DEF456", "classifyField": "description", "categories": ["Positive", "Negative", "Neutral"], "contextFields": ["rating", "author"] } ``` ### Suggest mode Not sure what categories make sense for your data? Enable **Suggest Categories From Sample** and leave the **Categories** field empty. The Actor will: 1. Read a sample (default 30 rows) from your dataset or CSV. 2. Ask the LLM to propose 5–10 mutually-exclusive, content-specific categories. 3. Write the proposals to the `SUGGESTED_CATEGORIES` record in the key-value store and log them to the run output. 4. Exit. No dataset rows are pushed in this mode, so it's much cheaper than a full classification. Review the suggestions, pick the ones you want, then re-run the Actor with **Suggest Categories From Sample** disabled and your chosen names in **Categories** to classify the full dataset. ### Iterative taxonomy refinement After your first real classification pass, some rows may have genuinely not fit any of your categories. Enable both **Allow UNCATEGORIZED** and **Suggest New Categories From UNCATEGORIZED** on the next run and the Actor will: 1. Classify normally, marking rows that don't fit as `"UNCATEGORIZED"`. 2. After classification finishes, sample up to **Sample Size** UNCATEGORIZED rows. 3. Ask the LLM for 3–7 *new* categories that would cover those rows (without overlapping your existing ones). 4. Write the proposals to `SUGGESTED_NEW_CATEGORIES` in the key-value store and log them. Add the names you like to **Categories**, re-run, and your `UNCATEGORIZED` count should drop. ### Output The Actor outputs the original dataset rows with one new field added. All original fields are preserved. | Field | Type | Description | |---|---|---| | `_classification` | string or string\[] | Assigned category (or array if multiple categories enabled) | #### Example output row ```json { "title": "Apple announces new M5 chip at WWDC", "url": "https://example.com/article/123", "description": "Apple unveiled its next-generation M5 processor...", "_classification": "Technology" } ``` Every row is classified into one of the categories you provide — even genuinely borderline content is forced into its closest-fitting category. If you need an explicit "doesn't fit" bucket, add it to your category list (e.g. `["Positive", "Negative", "Neutral"]`). Items that could not be classified are marked `"CLASSIFICATION_ERROR"`. This happens when: - The LLM kept returning malformed or unparseable responses for that row after retries. - The LLM returned a category that wasn't on your list (a hallucinated label). The Actor continues past errored rows rather than aborting, so a few bad rows don't kill a large job. Inspect `CLASSIFICATION_ERROR` rows after the run if you need to retry them separately. ### How to get a dataset ID Every Apify Actor run produces a dataset. You can find the dataset ID in several ways: 1. **From the Apify Console** — Open any Actor run, go to the Storage tab, and copy the dataset ID 2. **From the API** — The dataset ID is returned in the `defaultDatasetId` field of every run response 3. **From integrations** — When chaining Actors, pass the `defaultDatasetId` from one run as input to this Actor ### Pricing This Actor uses **pay-per-event** pricing with a small minimum charge per classified row, kept low to cover the underlying LLM cost and a thin margin. There is no monthly rental or platform-usage markup beyond the standard Apify costs (compute time, dataset operations) that any Actor incurs. See the Actor's pricing tab on Apify Store for the current per-item rate. ### Limitations - The text field must contain meaningful text for classification — empty or very short values may be classified as `UNCATEGORIZED` - Very long text fields (>2000 characters) are handled automatically but may slightly increase processing time - Maximum accuracy depends on how distinct your categories are — use category descriptions to improve results when categories overlap ### Acceptable use This Actor is a classification tool, not a general-purpose AI endpoint. Do not submit content that is unlawful, infringes third-party rights, or violates the terms of service of any underlying AI providers used by the Actor. You are responsible for the content you submit and for ensuring it is appropriate for automated processing. # Actor input Schema ## `datasetId` (type: `string`): Apify dataset to classify. Provide either this or a CSV file. ## `csvFile` (type: `string`): Upload a CSV file to classify. Provide either this or a Source Dataset. ## `classifyField` (type: `string`): Name of the text field/column to classify (e.g. "description", "title"). ## `categories` (type: `array`): List of target categories to classify rows into. Leave empty and enable "Suggest Categories From Sample" to have the Actor propose categories based on your data. ## `suggestCategoriesOnly` (type: `boolean`): Skip classification. Instead, sample rows from the dataset and ask the LLM to propose a useful set of categories. The suggestions are written to the SUGGESTED\_CATEGORIES key-value store record and logged. Re-run with the chosen names in "categories" to classify the full dataset. ## `sampleSize` (type: `integer`): How many rows to feed to the LLM when suggesting categories. Only used when "Suggest Categories From Sample" is enabled. ## `categoryDescriptions` (type: `object`): Optional map of category name → description for disambiguation. Example: {"Technology": "Software, hardware, AI, and IT topics"}. ## `contextFields` (type: `array`): Additional fields to include as context for classification (e.g. \["author", "source"]). ## `classificationFieldName` (type: `string`): Name of the new classification field added to each row. ## `allowMultipleCategories` (type: `boolean`): If enabled, rows can be assigned multiple categories (returned as an array). ## `allowUncategorized` (type: `boolean`): If enabled, the model may mark a row as "UNCATEGORIZED" when none of your categories fit. If disabled (default), the model is forced to pick the closest match from your list. ## `suggestNewFromUncategorized` (type: `boolean`): After classification finishes, sample the UNCATEGORIZED rows and ask the LLM to suggest new categories that would cover them. Output is written to the SUGGESTED\_NEW\_CATEGORIES key-value store record. Requires "Allow UNCATEGORIZED" to be enabled. ## `maxItems` (type: `integer`): Maximum number of items to process from the source dataset. Leave empty for all items. ## `model` (type: `string`): OpenRouter model slug (e.g. "openai/gpt-4o-mini", "anthropic/claude-3.5-haiku", "meta-llama/llama-3.1-8b-instruct"). Browse https://openrouter.ai/models for the full catalog. Cheaper models cost less in platform usage but may classify less reliably. ## Actor input object example ```json { "classifyField": "description", "categories": [ "Technology", "Business", "Entertainment", "Sports", "Science" ], "suggestCategoriesOnly": false, "sampleSize": 30, "classificationFieldName": "_classification", "allowMultipleCategories": false, "allowUncategorized": false, "suggestNewFromUncategorized": false, "model": "openai/gpt-4o-mini" } ``` # Actor output Schema ## `dataset` (type: `string`): No description ## `suggestedCategories` (type: `string`): No description ## `suggestedNewCategories` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "classifyField": "description", "categories": [ "Technology", "Business", "Entertainment", "Sports", "Science" ], "model": "openai/gpt-4o-mini" }; // Run the Actor and wait for it to finish const run = await client.actor("lukas.priban/dataset-classifier").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "classifyField": "description", "categories": [ "Technology", "Business", "Entertainment", "Sports", "Science", ], "model": "openai/gpt-4o-mini", } # Run the Actor and wait for it to finish run = client.actor("lukas.priban/dataset-classifier").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "classifyField": "description", "categories": [ "Technology", "Business", "Entertainment", "Sports", "Science" ], "model": "openai/gpt-4o-mini" }' | apify call lukas.priban/dataset-classifier --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=lukas.priban/dataset-classifier", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Dataset Classifier", "description": "Automatically classify rows in any Apify dataset into categories you define. Point it at a dataset, pick a text column, provide your categories, and get back the original data with a new classification column added.", "version": "0.0", "x-build-id": "lZlK7Vj8RATPuBbUa" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/lukas.priban~dataset-classifier/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-lukas.priban-dataset-classifier", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/lukas.priban~dataset-classifier/runs": { "post": { "operationId": "runs-sync-lukas.priban-dataset-classifier", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/lukas.priban~dataset-classifier/run-sync": { "post": { "operationId": "run-sync-lukas.priban-dataset-classifier", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "classifyField" ], "properties": { "datasetId": { "title": "Source Dataset", "type": "string", "description": "Apify dataset to classify. Provide either this or a CSV file." }, "csvFile": { "title": "CSV File", "type": "string", "description": "Upload a CSV file to classify. Provide either this or a Source Dataset." }, "classifyField": { "title": "Field to Classify", "type": "string", "description": "Name of the text field/column to classify (e.g. \"description\", \"title\")." }, "categories": { "title": "Categories", "type": "array", "description": "List of target categories to classify rows into. Leave empty and enable \"Suggest Categories From Sample\" to have the Actor propose categories based on your data.", "items": { "type": "string" } }, "suggestCategoriesOnly": { "title": "Suggest Categories From Sample", "type": "boolean", "description": "Skip classification. Instead, sample rows from the dataset and ask the LLM to propose a useful set of categories. The suggestions are written to the SUGGESTED_CATEGORIES key-value store record and logged. Re-run with the chosen names in \"categories\" to classify the full dataset.", "default": false }, "sampleSize": { "title": "Sample Size For Category Suggestion", "minimum": 5, "maximum": 100, "type": "integer", "description": "How many rows to feed to the LLM when suggesting categories. Only used when \"Suggest Categories From Sample\" is enabled.", "default": 30 }, "categoryDescriptions": { "title": "Category Descriptions", "type": "object", "description": "Optional map of category name → description for disambiguation. Example: {\"Technology\": \"Software, hardware, AI, and IT topics\"}." }, "contextFields": { "title": "Context Fields", "type": "array", "description": "Additional fields to include as context for classification (e.g. [\"author\", \"source\"]).", "items": { "type": "string" } }, "classificationFieldName": { "title": "Output Field Name", "type": "string", "description": "Name of the new classification field added to each row.", "default": "_classification" }, "allowMultipleCategories": { "title": "Allow Multiple Categories", "type": "boolean", "description": "If enabled, rows can be assigned multiple categories (returned as an array).", "default": false }, "allowUncategorized": { "title": "Allow UNCATEGORIZED", "type": "boolean", "description": "If enabled, the model may mark a row as \"UNCATEGORIZED\" when none of your categories fit. If disabled (default), the model is forced to pick the closest match from your list.", "default": false }, "suggestNewFromUncategorized": { "title": "Suggest New Categories From UNCATEGORIZED", "type": "boolean", "description": "After classification finishes, sample the UNCATEGORIZED rows and ask the LLM to suggest new categories that would cover them. Output is written to the SUGGESTED_NEW_CATEGORIES key-value store record. Requires \"Allow UNCATEGORIZED\" to be enabled.", "default": false }, "maxItems": { "title": "Max Items", "minimum": 1, "type": "integer", "description": "Maximum number of items to process from the source dataset. Leave empty for all items." }, "model": { "title": "LLM Model", "type": "string", "description": "OpenRouter model slug (e.g. \"openai/gpt-4o-mini\", \"anthropic/claude-3.5-haiku\", \"meta-llama/llama-3.1-8b-instruct\"). Browse https://openrouter.ai/models for the full catalog. Cheaper models cost less in platform usage but may classify less reliably." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```