# USPTO Trademarks Search, Status and Watch (`barefoot_grade/uspto-trademarks-scraper`) Actor

Search US trademarks, retrieve status and prosecution events, and watch new filings or publications. Text matching only; no legal clearance or similarity scoring.

- **URL**: https://apify.com/barefoot_grade/uspto-trademarks-scraper.md
- **Developed by:** [Philip Kirkbride](https://apify.com/barefoot_grade) (community)
- **Categories:** Lead generation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $4.00 / 1,000 rows

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## USPTO Trademarks Search, Status and Watch

Search US trademarks, retrieve application status and prosecution events, and watch for matching new filings or publications. Matching uses text and class filters. This actor does not provide similarity scoring, legal clearance, legal advice, or trademark infringement detection. It does not send email or other notifications; schedule watch runs and consume their dataset rows for alerts.

Search by word mark text, owner name phrase, international class, live/dead status and filing date. Status lookups accept serial or registration numbers. Watch rows explain which terms, owners, classes and dates matched.

### Input

The default returns up to 10 marks containing ORCHARD:

```json
{"mode":"search","terms":["ORCHARD"],"wordMatch":"contains","maxItems":10}
```

Word matching is case insensitive: `exact` matches the whole mark; `contains` matches a literal substring. Owner names use phrase matching, including the source's punctuation and word normalization. Values within each list are alternatives; different fields combine as AND filters. `internationalClasses` accepts three-digit strings `001`–`045`. `status` is `all`, `live` or `dead`. `filingDateFrom` and `filingDateTo` are inclusive `YYYY-MM-DD` bounds. `maxItems` is 1–10,000. Without explicit terms, ORCHARD is used only for a search with no owner or class filter.

```json
{"mode":"status","serialNumbers":["78787878"],"maxItems":10}
```

Alternatively use `registrationNumbers`. Clear search filters when selecting status mode. Each number returns one status row, including classes, goods/services, attorney and dated prosecution events when supplied. Missing registration numbers are confirmed twice; unavailable status details are reported as failed targets. This actor returns event text, without downloading document files.

```json
{"mode":"watch","terms":["ORCHARD"],"internationalClasses":["030"],"since":"2026-01-01","watchName":"orchard-class030","maxItems":1000}
```

A watch matches a filing **or** publication on or after `since`. For later runs, omit `since` to resume the same named watch. An explicit `since` replays that range. `watchName` accepts 1–80 letters, digits, underscores or hyphens. State is stored in the named `uspto-trademark-watches` key-value store under that name. Use distinct names for distinct filters and run a given watch sequentially. Without a name, watch mode is a date-filtered one-off export.

A complete run saves the newest matched event date and remembers the marks already delivered on that date. Truncated, interrupted or failed scans retain their checkpoint, so retries can repeat rows. Deduplicate by serial number and matched event date. Raising `maxItems` or narrowing the filters may be necessary to finish a watch. Late indexing of older filings/publications can fall behind a saved date; periodically replay an earlier `since` when completeness matters. Checkpoints are not a complete historical audit or a guarantee against missed changes. Status-only changes to existing marks are not watched.

### Output example

Rows use `rowType` values `searchResult`, `status` or `watchHit`. Common fields include serial/registration numbers, word mark, owners, status, live flag, filing/publication/registration dates, international classes, goods/services, attorney and a canonical TSDR `sourceUrl`. Numbers that serve as identifiers remain strings to preserve leading zeros. Search rows have null `statusDate` and empty detailed `classes`/`prosecutionEvents`; status rows populate them when available. Watch hits include `matchReasons`. Dates are ISO 8601 calendar dates; missing source fields are null or empty arrays.

```json
{
  "rowType": "searchResult",
  "serialNumber": "50012306",
  "registrationNumber": null,
  "wordMark": "HILLWOOD ORCHARDS WHERE HILLS NURTURE, FLAVOR THRIVES",
  "owners": [
    "PRODUCTORA INTERNACIONAL DE BEBIDAS, S.A. DE C.V. (CORPORATION; Mexico)"
  ],
  "status": "NEW APPLICATION - ASSIGNED TO EXAMINER",
  "statusDate": null,
  "live": true,
  "filingDate": "2026-07-24",
  "publicationDate": null,
  "registrationDate": null,
  "internationalClasses": [
    "029"
  ],
  "goodsAndServices": [
    "IC 029: Snack mix consisting primarily of processed nuts, and also including dried fruit, processed seeds and chocolate."
  ],
  "classes": [],
  "attorney": "BRUCE  MARGULIES",
  "prosecutionEvents": [],
  "sourceUrl": "https://tsdr.uspto.gov/#caseNumber=50012306&caseSearchType=US_APPLICATION&caseType=DEFAULT&searchType=statusSearch",
  "matchReasons": []
}
```

This example includes the complete common field set.

### Limits

Each search is limited to the source's first 10,000 results, ordered by serial number. The actor reports truncation explicitly. Date/class filters can narrow a search. Source data and indexing can lag official events. A row is a source snapshot, not a legal determination.

Rows save as pages finish. A run with saved rows succeeds and names failed or unfinished targets in its status. A confirmed empty result succeeds; an unavailable source with zero rows fails. Named watches do not advance on partial results. No account or API key is required.

### Local use

Install `requirements-dev.txt` in a virtual environment, then run `python -m unittest discover -s tests`. Run the actor with `python -m src`. Input and results use the standard Apify storage interface.

For any per-start billing, starts are counted per GB of memory; a default 512 MB run is one start. See the Store listing for current pricing.

# Actor input Schema

## `mode` (type: `string`):

Search marks, retrieve status by number, or watch new filings/publications.

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

Word mark text to match. Alternatives within this list; combined with owner/class filters. Defaults to ORCHARD only for an unfiltered search.

## `wordMatch` (type: `string`):

Exact whole word mark or literal substring (case insensitive). Applies to terms only.

## `owners` (type: `array`):

Owner name phrases, matched by the source phrase analyzer. Alternatives within this list.

## `internationalClasses` (type: `array`):

Three-digit Nice classes 001 through 045. Alternatives within this list.

## `status` (type: `string`):

Filter search/watch marks by current live/dead flag.

## `filingDateFrom` (type: `string`):

Inclusive filing date lower bound, YYYY-MM-DD; search/watch only.

## `filingDateTo` (type: `string`):

Inclusive filing date upper bound, YYYY-MM-DD; search/watch only.

## `since` (type: `string`):

Inclusive filing or publication date, YYYY-MM-DD. Required for a new watch. Explicit since replays that date range.

## `watchName` (type: `string`):

Persistent watch name: 1–80 letters, digits, underscores or hyphens. Uses the named uspto-trademark-watches store. Filters cannot change under an existing name.

## `serialNumbers` (type: `array`):

Eight-digit application serial numbers; status mode only.

## `registrationNumbers` (type: `array`):

Five to eight digits; status mode resolves each registration to a serial number.

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

Maximum delivered rows, 1–10000. A truncated watch does not advance its checkpoint. Status mode uses input target order.

## Actor input object example

```json
{
  "mode": "search",
  "terms": [
    "ORCHARD"
  ],
  "wordMatch": "contains",
  "status": "all",
  "maxItems": 10
}
```

# Actor output Schema

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

// Prepare Actor input
const input = {
    "terms": [
        "ORCHARD"
    ],
    "maxItems": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("barefoot_grade/uspto-trademarks-scraper").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": ["ORCHARD"],
    "maxItems": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("barefoot_grade/uspto-trademarks-scraper").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": [
    "ORCHARD"
  ],
  "maxItems": 10
}' |
apify call barefoot_grade/uspto-trademarks-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,barefoot_grade/uspto-trademarks-scraper"
        }
    }
}
```

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/DIoy4GuJzARvVkhke/builds/ZTLPbUxrcxBs1G2Lf/openapi.json