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.

{
  "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.

{
  "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.

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:

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:

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:

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:

{
  "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. It is a separate source/workflow; it does not expand this Actor's coverage.