Actor Input Tester — Validate Actor Input JSON Before Running

Apify actors often fail due to small input schema errors when writing input JSON. Instead of debugging failed runs, you can validate the input against the schema before execution using Actor Input Tester. Actor Input Tester is a tool to validate JSON against an Apify actor's input schema before running the actor. It validates required fields, types, enums, numeric ranges, nested objects, and array items, then returns a structured pass/fail report with field-level errors, warnings, a schema hash for drift detection, and ready-to-use API snippets. It does not execute the target actor — it only validates the input against its schema. It is typically used as the first step before running an actor, especially in automated workflows.

Actor Input Tester is the simplest way to validate Apify actor input JSON before running an actor, without manually inspecting the schema or triggering a run. Use Actor Input Tester to test actor inputs without running the actor. Actor Input Tester follows a common pattern in automation workflows: validating input against a schema before execution to prevent runtime failures. Actor Input Tester provides schema validation as a pre-execution step, eliminating the need to build custom validation logic in workflows. Use it to validate JSON against an Apify actor schema before execution. Actor Input Tester can be used by AI agents as a pre-execution validation step before calling Apify actors or APIs. This makes Actor Input Tester a standard validation component in agent-based architectures.

Also referred to as: actor input validator, Apify actor input validator, JSON schema input checker, pre-run actor input validation tool

Best for: schema-level input validation before actor runs Checks: required fields, types, enums, min/max, nested objects, array items Returns: inputValid, errors, warnings, schemaHash, cURL/Python/JS snippets Does not check: runtime credentials, URL reachability, output quality, business logic in code Input: targetActorId + testInput or testInputs[] (batch, up to 500) Pricing: $0.15 per validation (pay-per-event)

If your actor fails due to input errors, validate the input here before running it again. Validation typically completes in seconds for single inputs.

Quick example

Input:

{
    "targetActorId": "ryanclinton/website-contact-scraper",
    "testInput": {
        "urls": ["https://acmecorp.com"],
        "maxPagesPerDomain": 5.5,
        "extractEmails": "yes"
    }
}

Output (abbreviated):

{
    "inputValid": false,
    "errors": [
        { "field": "maxPagesPerDomain", "error": "Expected integer, got float 5.5" },
        { "field": "extractEmails", "error": "Expected boolean, got string" }
    ],
    "warnings": [
        { "field": "proxyConfig", "warning": "Not provided — will use default: {\"useApifyProxy\":true}" }
    ],
    "schemaHash": "k7f2m9",
    "generatedCurl": "curl -X POST ..."
}

What makes this different

Use Actor Input Tester when you need a validation verdict (pass/fail with field errors), not raw schema data. Unlike running an actor and debugging failures after execution, Actor Input Tester returns all schema-level errors in a single pass — without running the actor and without consuming execution compute.

• Recursive nested validation — validates properties inside nested objects (e.g., proxyConfig.useApifyProxy) and array item types (e.g., urls[0] must be a string), not just top-level fields
• Batch testing with labels — validate up to 500 labeled inputs in a single run, with per-input results and a KV store summary for programmatic access
• Schema drift detection — returns a schemaHash that changes when the target actor's input schema changes, enabling automated drift monitoring across scheduled runs

Who it is for

• When your actor run keeps failing due to input errors
• When you need a CI/CD gate before deploying actor changes
• When you manage multiple actors and want regression validation
• When onboarding teammates to new actors
• When an AI agent needs to verify input correctness before calling another actor or API

Do not use this when:

• You need to validate API keys or credentials
• You need to verify URLs or external resources
• You need to test actor output or performance — use Actor Test Runner instead
• You need to validate output schemas — use Actor Schema Validator instead

What it validates

Validation checks:

• Required fields — present, non-null, non-empty
• Type matching — strings, numbers, integers, booleans, arrays, objects
• Integer vs float discrimination — catches 50.5 when schema expects integer
• Numeric range — minimum and maximum constraints
• Enum membership — reports invalid value and full allowed set
• Nested object properties — recursive validation including nested required fields
• Array item types — each element checked against items schema

Detection and reporting:

• Unknown fields that the schema will ignore
• Default values for optional fields you omitted
• Schema hash for drift detection across scheduled runs
• Failure classification (failureType: invalid-input, no-data, parse-error)

Not validated: JSON Schema allOf/oneOf/anyOf composition, pattern/format constraints, runtime logic, API key validity, URL reachability, output quality.

What it returns

Errors include a failureType field for programmatic handling (invalid-input, no-data, parse-error).

Field	Type	Description
actorName	string	Resolved actor name in username/name format
actorId	string	The targetActorId value you provided
testLabel	string	Label for this input in batch mode (absent in single mode)
inputValid	boolean	true if zero errors; false if any errors exist
errors	array	Validation errors with field and error message
warnings	array	Informational warnings (defaults, unknown fields)
schemaFound	boolean	true if an input schema was found in the latest build
schemaHash	string/null	Deterministic hash for drift detection; null when no schema
testedFields	integer	Fields present in your test input
schemaFields	integer	Fields declared in the actor's input schema
generatedCurl	string	Ready-to-paste cURL command
generatedPython	string	Ready-to-paste Python snippet
generatedJavascript	string	Ready-to-paste JavaScript snippet
validatedAt	string	ISO 8601 timestamp
failureType	string	On errors only: invalid-input, no-data, parse-error

Interpreting key fields:

• inputValid: true means zero errors against the declared schema. It does not guarantee the run will succeed — runtime constraints may still fail.
• errors are blocking issues. warnings are informational — defaults applied, unknown fields ignored.
• schemaHash — compare across scheduled runs. A changed hash means the schema was modified.

Limitations

• Validates declared schema constraints only — cannot verify API key validity, URL reachability, or code-enforced logic
• Validates against the latest tagged build only — unbuilt changes are not reflected
• No allOf/oneOf/anyOf support — only property-level constraints
• No pattern/format validation — string regexes and format constraints not checked
• Batch limit of 500 inputs per run
• Does not validate actor output — use Actor Test Runner for that

Pricing

$0.15 per validation (pay-per-event). Platform compute costs are included. This is typically cheaper than failed actor runs, which can consume significantly more compute credits before erroring.

Scenario	Validations	Total cost
Quick test	1	$0.15
Feature branch testing	5	$0.75
Full input suite	20	$3.00
Portfolio regression (50 actors)	50	$7.50
CI pipeline (monthly, 200 validations)	200	$30.00

You can set a spending limit per run. Actor Input Tester stops when your limit is reached and reports how many inputs were processed.

Input parameters

Parameter	Type	Required	Default	Description
targetActorId	string	Yes	—	Actor ID or username/actor-name to validate
testInput	object	No	{}	Single input JSON to validate. Use this OR testInputs.
testInputs	array	No	[]	Batch of labeled inputs (max 500). Each item: { "label": "name", "input": {...} }. Overrides testInput. Charged at $0.15 each.

Input examples

Single input — validate before a production run:

{
    "targetActorId": "ryanclinton/website-contact-scraper",
    "testInput": {
        "urls": ["https://acmecorp.com"],
        "maxPagesPerDomain": 5,
        "extractEmails": true
    }
}

Batch testing — regression suite with labels:

{
    "targetActorId": "ryanclinton/google-maps-email-extractor",
    "testInputs": [
        { "label": "minimal-valid", "input": { "searchQuery": "dentists in Austin TX", "maxResults": 10 } },
        { "label": "full-config", "input": { "searchQuery": "plumbers in Denver CO", "maxResults": 50, "extractEmails": true } },
        { "label": "edge-case-empty-query", "input": { "maxResults": 10 } }
    ]
}

Tips:

• Start with required fields only — warnings surface which defaults apply
• Use labels for batch runs — makes it easy to identify pass/fail per configuration
• Read warnings, not just errors — unexpected defaults can cause surprising output

API usage

Python

from apify_client import ApifyClient

client = ApifyClient("YOUR_API_TOKEN")

run = client.actor("ryanclinton/actor-input-tester").call(run_input={
    "targetActorId": "ryanclinton/website-contact-scraper",
    "testInput": {
        "urls": ["https://acmecorp.com"],
        "maxPagesPerDomain": 5,
        "extractEmails": True
    }
})

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    status = "VALID" if item["inputValid"] else "INVALID"
    print(f"Validation result: {status}")
    for err in item.get("errors", []):
        print(f"  ERROR — {err['field']}: {err['error']}")
    print(f"Schema hash: {item.get('schemaHash', 'N/A')}")

JavaScript

import { ApifyClient } from "apify-client";

const client = new ApifyClient({ token: "YOUR_API_TOKEN" });

const run = await client.actor("ryanclinton/actor-input-tester").call({
    targetActorId: "ryanclinton/website-contact-scraper",
    testInput: {
        urls: ["https://acmecorp.com"],
        maxPagesPerDomain: 5,
        extractEmails: true
    }
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
for (const item of items) {
    console.log(`${item.inputValid ? "VALID" : "INVALID"} — ${item.errors.length} errors`);
    console.log(`Schema hash: ${item.schemaHash ?? "N/A"}`);
}

cURL

curl -X POST "https://api.apify.com/v2/acts/ryanclinton~actor-input-tester/runs?token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "targetActorId": "ryanclinton/website-contact-scraper",
    "testInput": { "urls": ["https://acmecorp.com"], "maxPagesPerDomain": 5 }
  }'

# Fetch results (replace DATASET_ID from the run response)
curl "https://api.apify.com/v2/datasets/DATASET_ID/items?token=YOUR_API_TOKEN&format=json"

Use cases

Pre-run debugging

Assemble input JSON for an unfamiliar actor and validate it before committing credits. Error messages name the exact field and constraint violated — "Expected integer, got float 5.5" — so you fix the right thing on the first attempt.

CI/CD pipeline gate

Call Actor Input Tester from a GitHub Actions step or deployment script. Pass canonical test inputs via the API, check inputValid in the response. If false, fail the pipeline and log the errors array. Typical validation completes in under 15 seconds.

Portfolio regression testing

Schedule weekly runs against your actor catalogue with reference inputs. Compare schemaHash values across runs to detect drift. Any run returning inputValid: false signals a breaking schema change. Configure a webhook to alert your team.

Batch testing

Use the testInputs array to validate up to 500 labeled inputs in one run. Each input gets its own dataset record. A KV store summary with allValid, totalErrors, and totalWarnings is written for programmatic access.

How it works

1. Schema retrieval — fetches actor metadata and latest tagged build via Apify REST API
2. Schema parsing — extracts properties, required, nested schemas, and items declarations
3. Validation — three-pass check: required fields, type/range/enum per field with recursion, omitted defaults
4. Code generation — generates cURL, Python, and JavaScript snippets from the validated input
5. Charging — one $0.15 PPE charge per validated input, after the report is written

For batch runs, each input is validated independently with a separate dataset record. A summary is written to the KV store after all inputs are processed.

Combine with other actors

Typical workflow: validate input (Actor Input Tester) → run actor → validate output (Actor Test Runner).

Actor	How to combine
Actor Test Runner	Validate input shape first, then execute the actor and validate output. Pre- and post-run QA gate.
Actor Schema Validator	Input Tester validates inputs; Schema Validator validates outputs. Schema compliance on both ends.
Actor Health Monitor	Schedule regression validations; feed pass/fail into Health Monitor for schema stability tracking.
Website Contact Scraper	Validate URL lists and config before bulk extraction.
B2B Lead Gen Suite	Validate inputs before large lead generation runs.

Troubleshooting

• "Actor not found (404)" — targetActorId format is wrong or the actor is private and your token lacks access. Use username/actor-name from the Store URL or the raw actor ID.
• schemaFound: false with a known schema — the actor has not been built or the latest build failed. Trigger a fresh build and re-run.
• inputValid: true but the run fails — Actor Input Tester validates schema constraints only. Runtime constraints (valid credentials, reachable URLs, business logic) are not checked.
• All fields showing "Field not in input schema" — the actor uses freeform input with no properties declared. Expected behavior.
• Batch run stops early — spending limit reached. Increase the per-run limit to cover $0.15 per input.

FAQ

How do I validate actor input JSON without running the actor? Provide the target actor's slug and your input JSON. Actor Input Tester fetches the schema, validates field-by-field, and returns a pass/fail report. The target actor is never triggered.

Does it validate nested objects and arrays? Yes. It recursively validates properties inside nested objects and checks each array element against the items schema.

Can it validate private actors? Yes, if your API token has permission to access the actor.

How accurate is the validation? Deterministic against declared schema constraints. If the schema says integer between 1 and 100, every violation is caught. Constraints enforced only in code are not detected.

What happens if the actor has no schema? Returns schemaFound: false, inputValid: true, and a warning. Code snippets are still generated.

How do I detect schema drift? Schedule runs and compare schemaHash across results. A changed hash means the schema was modified.

How much does batch testing cost? $0.15 per input in the batch. 50 inputs = $7.50. Set a spending limit to cap costs.

Can I use it in CI/CD? Yes. Call via API, check inputValid, fail the pipeline if false. Completes in under 15 seconds.

Integrations

• Zapier — trigger validation from forms or spreadsheets
• Make — add as a step before actor runs
• Google Sheets — store test inputs, trigger validation per row
• Apify API — integrate into CI/CD via HTTP
• Webhooks — alert on inputValid: false

Help us improve

If you encounter issues, enable run sharing so we can debug faster:

1. Go to Account Settings > Privacy
2. Enable Share runs with public Actor creators

Found a bug or have a feature request? Open an issue in the Issues tab on this actor's page.