# Actor Run Search (`true.false.maybe/actor-run-search`) Actor

Find historical Apify Actor runs by searching run inputs for exact or partial text matches. Quickly locate run IDs without manually browsing run history.

- **URL**: https://apify.com/true.false.maybe/actor-run-search.md
- **Developed by:** [TrueFalseMaybe](https://apify.com/true.false.maybe) (community)
- **Categories:** Automation, Integrations, Developer tools
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 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/actors/running/actors-in-store.md#pay-per-usage

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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

## Apify Run Input Search (Apify Actor)

This Apify Actor searches through an Actor’s historical run inputs and finds runs containing a specific keyword, phrase, URL, or partial text match.

The Actor scans all available runs, loads each run’s `INPUT` record from its Key-Value Store, and performs a case-insensitive text search against the full JSON input.

Results are exported into an Apify Dataset for easy filtering, analysis, or debugging.

***

### How It Works

The Actor:

1. Fetches all runs from a target Actor
2. Extracts each run’s Key-Value Store ID
3. Loads the `INPUT` record from every run
4. Converts the input JSON into searchable text
5. Searches for a user-provided term
6. Stores matching runs in the Dataset

***

### Use Cases

- Find runs containing a specific URL
- Locate runs by keyword or product name
- Search historical automation inputs
- Recover lost run configurations
- Audit old Actor runs
- Investigate customer executions
- Debug large-scale automation workflows

***

## Input Options

### `actorId`

The Actor ID whose runs should be searched.

- **Type:** `string`
- **Required:** yes

```json
"actorId": "nwua9Gu5YrADL7ZDj"
```

***

### `searchTerm`

Text to search for inside run inputs.

Supports:

- URLs
- partial strings
- keywords
- JSON fragments
- usernames
- arbitrary text

Search is:

- case-insensitive

- partial-match based

- **Type:** `string`

- **Required:** yes

```json
"searchTerm": "kitchenaid"
```

```json
"searchTerm": "https://www.ebay.com/usr/kitchenaid"
```

***

### `apiToken`

Apify API token used to read the target Actor's runs and key-value stores.

- **Type:** `string`
- **Required:** yes
- Hidden securely in Actor input UI

```json
"apiToken": "apify_api_xxxxxxxxx"
```

#### Security: use a limited-permission token

The Actor no longer falls back to its own run token — you must supply `apiToken` explicitly. This is intentional: the run's own token typically carries the **full permissions of the account that started the run** (read/write access to all Actors, runs, storages, etc.), while this Actor only ever performs read-only requests (listing runs, reading `INPUT` records). Requiring an explicit token forces a deliberate, scoped choice instead of silently inheriting full account access.

Recommended setup:

- In Apify Console, go to **Settings → Integrations → API tokens** and create a **limited token**.
- Scope it to read-only permissions on the specific Actor(s) whose runs you want to search (runs and key-value stores).
- Pass that limited token via the `apiToken` input field.

This way, even if the token were leaked or the Actor misused, the blast radius is capped to read access on one Actor's run history rather than the whole account.

***

### `stopIfMatchFound`

Controls whether the Actor stops after finding the first match.

#### `true`

- Stops early
- Faster execution
- Lower API usage

#### `false`

- Processes all runs

- Finds every possible match

- Pushes all matches to dataset

- **Type:** `boolean`

- **Default:** `true`

```json
"stopIfMatchFound": false
```

***

### `concurrency`

Number of runs processed simultaneously.

Higher values:

- increase speed
- increase API request volume

Recommended:

- `10-100` for most cases

- `100-500+` for aggressive searching

- **Type:** `integer`

- **Default:** `50`

```json
"concurrency": 100
```

***

## Full Input Example

```json
{
  "actorId": "nwua9Gu5YrADL7ZDj",
  "searchTerm": "kitchenaid",
  "apiToken": "apify_api_xxxxxxxxx",
  "stopIfMatchFound": false,
  "concurrency": 100
}
```

***

## Output

Each dataset item represents one matching run input.

***

### Output Fields

| Field | Type | Description |
| --- | --- | --- |
| `runId` | `string` | Apify Run ID |
| `storeId` | `string` | Key-Value Store ID associated with the run |
| `matchedTerm` | `string` | Search term used |
| `matched` | `boolean` | Indicates successful match |
| `inputPreview` | `string` | Truncated preview of input JSON |
| `input` | `object` | Full original INPUT payload |

***

## Output Example

```json
{
  "runId": "3KH8s2a9LmP4xQvWc",
  "storeId": "Jt9mKz1vQaY2LpNs",
  "matchedTerm": "kitchenaid",
  "matched": true,
  "inputPreview": "{\"startUrls\":[{\"url\":\"https://www.ebay.com/usr/kitchenaid/"}]}",
  "input": {
    "startUrls": [
      {
        "url": "https://www.ebay.com/usr/kitchenaid"
      }
    ]
  }
}
```

***

## Dataset Views

The Actor includes multiple Dataset views:

| View | Description |
| --- | --- |
| `Overview` | General match overview |
| `Matches` | Match-focused output |
| `Input Data` | Full input payloads |
| `Store IDs` | IDs only |

***

## Notes

- The Actor searches only the `INPUT` record of each run
- Search uses `JSON.stringify(input).includes(...)`
- Matching is case-insensitive
- Extremely large Actors may take significant time to process
- Private Actors require a valid API token with access
- The Actor runs with 1024 MB of memory by default, matching its lightweight, read-only API usage

***

## Legal Disclaimer

This Actor is not affiliated with or endorsed by Apify.

Users are responsible for:

- complying with Apify Terms of Service
- respecting account permissions
- ensuring authorized access to searched Actors

# Actor input Schema

## `actorId` (type: `string`):

ID of the Actor whose runs should be searched.

## `searchTerm` (type: `string`):

Keyword, URL, phrase, or partial text to search for inside run inputs.

## `stopIfMatchFound` (type: `boolean`):

If enabled, the Actor stops after finding the first batch containing matches.

## `concurrency` (type: `integer`):

Number of runs processed simultaneously.

## `apiToken` (type: `string`):

Apify API token used to read the target Actor's runs and key-value stores. Use a limited/scoped token (read-only access to the target Actor) rather than a full-access account token — see the README for details.

## Actor input object example

```json
{
  "stopIfMatchFound": false,
  "concurrency": 50
}
```

# Actor output Schema

## `overview` (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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("true.false.maybe/actor-run-search").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("true.false.maybe/actor-run-search").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 '{}' |
apify call true.false.maybe/actor-run-search --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,true.false.maybe/actor-run-search"
        }
    }
}

```

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/bbfdrSL0IiufCaxTj/builds/yagw4fwQfa5gI2PVa/openapi.json