# Urban Dictionary Definitions Scraper (`automation-lab/urban-dictionary-definition-lookup`) Actor

Look up supplied slang terms and export Urban Dictionary definitions, examples, public authors, vote counts and source links for recurring language datasets.

- **URL**: https://apify.com/automation-lab/urban-dictionary-definition-lookup.md
- **Developed by:** [Automation Lab](https://apify.com/automation-lab) (community)
- **Categories:** Education
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.94 / 1,000 item extracteds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Urban Dictionary Definitions Scraper

Refresh urban dictionary definitions for supplied slang terms and export structured entries for language research, lexicon datasets and recurring vocabulary analysis. Each row includes a definition, usage example, public author name, source-reported votes and a canonical entry URL.

This Actor retrieves the public API snapshot: normally up to ten definitions per term. It does not promise every definition, historical votes, comprehensive monitoring or authoritative meanings.

### Who is this for?

- Language researchers collecting a reproducible list of current slang entries.
- Data engineers refreshing a known term list on a schedule.
- Editorial teams comparing informal usage examples with formal dictionary records.

### Why use this Actor?

Get typed rows without parsing pages or managing a browser. Stable definition IDs support downstream joins; observation timestamps distinguish separate snapshots. Limits apply both globally and per term, and duplicate definition IDs are exported once per run.

The Actor preserves source text, including bracketed cross-links and newlines. It does not silently replace community language with generated definitions.

### What data is extracted?

| Field | Meaning |
|---|---|
| `query` | Trimmed supplied lookup term |
| `term` | Source word, retaining capitalization |
| `definitionId` | Stable public definition ID |
| `definition` | Source definition text, including bracketed cross-links |
| `example` | Source usage example; may be empty |
| `author` | Public display name, not verified identity |
| `thumbsUp` | Source-reported upvotes at lookup time |
| `thumbsDown` | Source-reported downvotes at lookup time |
| `writtenOn` | Source submission timestamp |
| `sourceUrl` | Canonical definition URL |
| `observedAt` | UTC time the response was normalized |

Vote values can be zero. The current public source may show zero even for old entries; this Actor does not infer historical totals. Definitions are user-contributed and can be offensive, inaccurate or unsuitable for minors.

### Getting started

1. Open the Actor input editor.
2. Supply terms such as `larp`, `glazing` and `trade`.
3. Choose a global limit and a per-term limit.
4. Run once and inspect the Definitions dataset.
5. Download JSON, CSV or Excel through Apify's dataset export tools.

```json
{
  "terms": ["larp", "glazing", "trade"],
  "maxItems": 100,
  "maxDefinitionsPerTerm": 10
}
```

### Input parameters

| Parameter | Default | Behavior |
|---|---|---|
| `terms` | Required | 1–100 nonempty strings; each at most 200 characters after trimming |
| `maxItems` | 20 | Global unique definition cap, 1–1000 |
| `maxDefinitionsPerTerm` | 10 | Unique rows saved per term, 1–10 |

Whitespace at the ends is removed. Case-insensitive duplicate terms are requested once in original order. Internal whitespace is preserved. Each term is passed whole to Urban Dictionary's lookup API; source matching and ordering are controlled by Urban Dictionary. This is not a custom substring, phrase or whole-word filter.

The global limit takes precedence. Later terms are not fetched after it is reached. Zero is invalid, not unlimited. Source IDs are deduplicated across terms; when an entry appears more than once, the first matching query owns its row. Unsupported fields are rejected rather than silently ignored.

### Example output

A larp lookup returned this definition shape. The author is anonymized in this documentation; actual output retains the public display name. Text is shortened for readability.

```json
{
  "query": "larp",
  "term": "LARP",
  "definitionId": 257215,
  "definition": "Live Action Role Play\r\n\r\na type of [game]...",
  "example": "[www].nerolarp.com...",
  "author": "Example Author",
  "thumbsUp": 0,
  "thumbsDown": 0,
  "writtenOn": "2003-09-18T00:00:00.000Z",
  "sourceUrl": "https://www.urbandictionary.com/define.php?term=LARP&defid=257215",
  "observedAt": "2026-10-04T20:06:54.723Z"
}
```

The default dataset contains only definitions. The lookup summary key-value record reports saved rows, empty terms and the coverage statement; its cost is included in the start fee.

### How much does it cost to look up Urban Dictionary definitions?

Pay-per-event pricing has one start fee of **$0.005 per run**, plus a charge for each unique definition saved. Empty lookups produce no definition event but a valid started run still has the start fee. Rejected or duplicate records are not charged as definitions.

| Tier | Price per definition |
|---|---:|
| FREE | $0.001794 |
| BRONZE | $0.00156 |
| SILVER | $0.0012168 |
| GOLD | $0.000936 |
| PLATINUM | $0.000936 |
| DIAMOND | $0.000936 |

At BRONZE, one definition is $0.00656 including the start fee; ten are $0.0206; thirty are $0.0518; one hundred are $0.161. At FREE, ten are $0.02294. These examples describe Actor event fees, not third-party integration charges. The live pricing panel is authoritative.

### Coverage and limitations

- A response snapshot normally contains at most ten definitions per term.
- No pagination, complete archive, random discovery or word-of-day mode is offered.
- The Actor has no login, account scraping, voting or personal-profile enrichment.
- It cannot prove that an absent definition was deleted; snapshots are incomplete.
- The source may change order, matching, content or vote visibility at any time.
- A failed run may retain already-saved rows; treat them as partial output.
- Runtime and customer spending limits can stop collection before requested limits.

### Reliability and troubleshooting

Requests are sequential. Network failures, rate limits and server errors have at most three attempts with bounded backoff and a 20-second timeout per request. Permanent refusals, malformed responses and non-JSON pages fail instead of appearing as successful empty results. No automatic proxy or browser fallback is enabled.

If a term has no definitions, the dataset has no row for it and `SUMMARY.emptyTerms` includes it. Check spelling and compare the public source. If a run fails, inspect its status and log before using any partial rows. A later retry is a new snapshot, not continuation of the previous dataset.

### Integrations and recurring refreshes

Schedule the same input in Apify to obtain separate snapshots. Store `definitionId` with `observedAt` in your warehouse and compare definition text or examples downstream. Do not interpret missing snapshot rows as deletions.

Use dataset exports for spreadsheets, webhooks for a pipeline completion trigger, and Apify API reads for ETL. Monitoring, diffing and alerts belong to your downstream workflow; the Actor itself does not provide them.

### API usage

Keep your Apify token private. Start one run, retain its ID, wait for terminal success and then fetch its bounded default dataset.

```bash
curl -X POST 'https://api.apify.com/v2/acts/automation-lab~urban-dictionary-definition-lookup/runs' \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"terms":["larp"],"maxItems":10}'
```

JavaScript with the official client:

```javascript
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/urban-dictionary-definition-lookup')
  .call({ terms: ['larp'], maxItems: 10 });
if (run.status !== 'SUCCEEDED') throw new Error(`Run ${run.id}: ${run.status}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems({ limit: 10 });
console.log(items);
```

Python with the official client:

```python
import os
from apify_client import ApifyClient
client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('automation-lab/urban-dictionary-definition-lookup').call(
    run_input={'terms': ['larp'], 'maxItems': 10})
if run['status'] != 'SUCCEEDED':
    raise RuntimeError(f"Run {run['id']}: {run['status']}")
print(client.dataset(run['defaultDatasetId']).list_items(limit=10).items)
```

### MCP usage

Select the stable Actor-specific hosted endpoint:

```bash
claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/urban-dictionary-definition-lookup"
```

Claude Desktop, Cursor, and VS Code: use the equivalent editor configuration below, adapted to your client's HTTP MCP support:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/urban-dictionary-definition-lookup"
    }
  }
}
```

Authenticate through your client's supported private credential setup. Actor selection also exposes run/data tools; it does not mean exactly one tool. Discover actual names and input schemas using read-only `tools/list`.

Example prompt: “Look up larp and glazing, save at most five definitions each, and show source URLs. Start only one run.” For authorized execution, retain the returned run and storage IDs. They are metadata, not results. If the run is not terminal, check that same run with 2/4/8-second backoff capped at ten seconds, stopping after 120 seconds. Configure transport timeout above the selected server wait (up to 45 seconds) plus margin. Recover the known run after client timeout instead of restarting it.

After success, read bounded dataset pages with explicit limit, offset and fields. A sensible consumer budget is twenty source rows per page, at most one hundred rows and 64 KiB serialized UTF-8 admitted to model context, whichever comes first. Enforce bytes host-side and disclose omitted or summarized oversized rows. Track source offsets, report partial/truncated status and continuation offset; keep full exports outside model context. If your client cannot intercept oversized responses, do not claim a hard byte guarantee. Report pending or failed status honestly. Tool discovery bytes are not automatically model-visible context; no universal token savings are promised.

### Legality and responsible use

Use only lawful purposes and respect Urban Dictionary terms, attribution, copyright and applicable data-protection requirements. Public display names are not permission to profile individuals or redistribute copyrighted material without appropriate rights. This Actor is independent and not endorsed by Urban Dictionary. It makes no legal compliance guarantee.

Failed operations send sanitized diagnostic input, exceptions and Actor/build/run IDs to our private GlitchTip service for repair. Secret fields and URL queries are removed. Reports are retained for 30 days. Do not submit private or sensitive text as lookup terms. The Actor uses no runtime AI provider and generates no definitions. Urban Dictionary receives the supplied lookup term; Apify stores results and logs under your account's storage policy. Delete runs, datasets and key-value stores through Apify when no longer needed. There is no separate application cache. For help, use the Actor's Apify Issues tab; never post credentials or sensitive terms in public support messages.

### FAQ

**Does this return every definition?** No. It exports the current public API snapshot, normally up to ten per term.

**Why are votes zero?** The public source can report zero. The Actor preserves that value without reconstructing historical counts.

**Does it strip bracketed links?** No. Brackets and source newlines are preserved for transparent downstream normalization.

**Can I refresh weekly?** Yes, through Apify schedules. Compare snapshots downstream; no built-in historical monitor or alert is included.

**Why did I receive fewer rows?** A term may have fewer entries; deduplication, source snapshot size, global/per-term limits or spending/runtime limits may apply.

### Related Actors

For formal lexical records rather than community slang, see [Spanish Wiktionary Definitions & Lexical Records](https://apify.com/automation-lab/spanish-wiktionary-definitions). It is a separate source/workflow; it does not expand this Actor's coverage.

# Changelog

This Actor's version history is a separate document: https://apify.com/automation-lab/urban-dictionary-definition-lookup/changelog.md

# Actor input Schema

## `terms` (type: `array`):

1–100 terms, each 1–200 characters after trimming. Surrounding whitespace is removed; case-insensitive duplicate inputs are requested once. Each term is passed whole to Urban Dictionary's lookup API; source matching and order are controlled by Urban Dictionary, not an Actor substring or whole-word filter.

## `maxItems` (type: `integer`):

Global cap of unique definition rows across all terms, processed in input order. Default 20; range 1–1000. Zero is invalid. Deduplication uses the source definition ID. Later terms are not fetched after the cap is reached; no pagination or complete-archive coverage is promised.

## `maxDefinitionsPerTerm` (type: `integer`):

Cap of unique rows saved for each term, in API response order. Default 10; range 1–10. The public snapshot normally returns at most ten records; fewer may exist. The global maxItems cap takes precedence. Zero is invalid.

## Actor input object example

```json
{
  "terms": [
    "larp",
    "glazing",
    "trade"
  ],
  "maxItems": 20,
  "maxDefinitionsPerTerm": 10
}
```

# Actor output Schema

## `dataset` (type: `string`):

Default dataset of unique definitions in the overview table.

## `summary` (type: `string`):

Saved count and terms with no entries; no separate charge.

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "terms": [
        "larp",
        "glazing",
        "trade"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/urban-dictionary-definition-lookup").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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "terms": [
        "larp",
        "glazing",
        "trade",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/urban-dictionary-definition-lookup").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "terms": [
    "larp",
    "glazing",
    "trade"
  ]
}' |
apify call automation-lab/urban-dictionary-definition-lookup --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automation-lab/urban-dictionary-definition-lookup"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/bDXN7YLwyrKX2czz6/builds/7aF3SY3haww4AFJIp/openapi.json