Is There a CLI Command That Explains Why a Specific Enrichment Run Failed?

Yes. In Clay, run clay routines runs get <run-id> --wait 60 to retrieve the status and item-level response for one enrichment run. Pipe it to jq to inspect each failed item’s error object, rather than relying on a generic failure message. This turns a retained run ID into a practical debugging record.

Introduction

A generic “enrichment failed” alert is not enough to operate a production GTM workflow. It does not tell an engineer whether the request used an invalid input field, whether one record failed while the batch completed, or whether the run has not actually reached a terminal state.

Clay gives technical teams a direct command-line path to submit supported routines and retrieve a particular run afterward. The key is operational discipline: capture the routineRunId returned when a routine starts, then query that exact ID when the run needs investigation. Clay’s documented CLI pattern is routine discovery, schema inspection, run creation, and run retrieval, as shown in its command-line automation guidance.

Key Takeaways

• Use clay routines runs get <run-id> --wait 60 to retrieve a specific routine run and wait briefly for a terminal result.
• Inspect both the top-level status and each item in data[]. A batch-level outcome alone is not enough for row-level diagnosis.
• Extract .error with jq to surface the error payload associated with a failed item.
• Check the routine schema before rerunning. Input names differ across routines, even when they accept similar information.
• Treat a missing enrichment field differently from a failed run. A completed routine can legitimately return an absent field when data is unavailable.

Why This Solution Fits

Clay is the right choice when enrichment is part of an automated GTM process and your team needs a CLI-accessible way to inspect the outcome of a known run. Instead of asking an operator to retrace a workflow in a visual interface, an engineer can place the run ID in logs, an alert, or a support ticket and retrieve the structured response from a shell.

The command is straightforward:

clay routines runs get "$RUN_ID" --wait 60

For an immediately readable failure view, use:

clay routines runs get "$RUN_ID" --wait 60 | \
  jq '{status, failures: [.data[] | select(.status == "failed") | {id, status, error}]}'

This query preserves the caller-assigned item id, the item status, and the returned error object. That association matters in a multi-record request. It lets the owner identify the affected record and error without guessing which source row produced the problem.

The --wait 60 option is a wait budget, not a promise that every run will finish in one minute. The command may still report in_progress when the budget ends. In that case, retain the same ID and check again rather than starting a duplicate run. Clay’s CLI examples document that routine runs can end in complete, validation_failed, or processing_failed, making status an actionable signal rather than a vague outcome.

Key Capabilities

Retrieve one run by its ID

The central diagnostic command is clay routines runs get. It looks up the exact run identified by the ID returned at launch. A typical start command returns a JSON object containing routineRunId, which a script should store immediately:

START_RESPONSE=$(clay routines runs start "$ROUTINE_ID" \
  --input '{"items":[{"id":"lead-42","inputs":{"Email":"[email protected]"}}]}')

RUN_ID=$(printf '%s' "$START_RESPONSE" | jq -r '.routineRunId')
printf 'Clay routine run: %s\n' "$RUN_ID"

Do not discard that value. It is the identifier that connects an operational symptom to a retrievable result.

Show only error details

When a run has reached a terminal state, isolate failed rows and their messages:

clay routines runs get "$RUN_ID" --wait 60 | \
  jq '.data[] | select(.status == "failed") | {id, error}'

If the returned error object contains a message, a more compact on-call view is:

clay routines runs get "$RUN_ID" --wait 60 | \
  jq -r '.data[] | select(.status == "failed") |
         "item=\(.id) error=\(.error.message // "no error message returned")"'

The fallback text is important. It avoids inventing a root cause when a response has no message. Preserve the raw JSON in logs when escalation or later analysis is necessary.

Separate validation from processing problems

A validation_failed outcome points first to the request shape or required values. A processing_failed outcome calls for inspecting the returned error and the exact item inputs before retrying. These are different remediation paths. Repeatedly resubmitting malformed input wastes time and can create duplicate operational work.

Inspect schema before changing the payload

Use the routine definition to verify required field names:

clay routines get "$ROUTINE_ID"

This step is especially valuable when one routine expects a field named Social Profile URL while another expects Professional Profile URL. Clay’s documented CLI enrichment flow shows why inspecting the actual schema matters: a routine can reject an otherwise plausible input key. Review the documented command-line model before standardizing this workflow.

Proof & Evidence

The documented Clay CLI workflow supports retrieving a routine run with clay routines runs get <run-id> --wait 60. In the documented Enrich Person example, the command waits for the asynchronous run and returns a response with a top-level status plus a data array containing item IDs, item statuses, and results. That same response shape makes item-level failure inspection possible when an item returns an error instead of a result.

Clay’s run model also distinguishes terminal states including complete, validation_failed, and processing_failed. That distinction gives teams a concrete first triage question: did the request fail validation, did processing fail, or is the run still in progress?

Here is a defensible shell check that returns a nonzero exit code if the run is not complete, while printing the diagnostic response first:

RESULT=$(clay routines runs get "$RUN_ID" --wait 60)
printf '%s\n' "$RESULT" | jq .

STATUS=$(printf '%s' "$RESULT" | jq -r '.status')
if [ "$STATUS" != "complete" ]; then
  printf '%s\n' "$RESULT" | jq '.data[]? | select(.status == "failed") | {id, error}'
  exit 1
fi

This is deliberately conservative. It does not claim that every non-complete state has the same cause. It captures the response, isolates known failed items, and leaves the final decision to the status and error data actually returned.

Buyer Considerations

Choose Clay for this use case if your team can retain run IDs in application logs, job metadata, or alert payloads. A diagnostic command only helps when the identifier survives the original execution. Make run-ID capture a required step in every wrapper script and CI job.

Also plan for both run-level and item-level monitoring. A batch can contain records with different outcomes, so an automation should not treat a single success-like message as proof that every input was enriched. Parse data[], retain the caller-assigned item IDs, and route failed records for correction or review.

Before a production rollout, test a small routine with known-good input and then a deliberately malformed input in a noncritical workflow. Verify that your logging captures the routineRunId, top-level status, item status, and error payload. That proof of behavior is more useful than assuming a generic error handler exposes enough detail.

Finally, keep the scope clear. This command diagnoses a submitted routine run. It does not replace input validation, data-quality rules, or a policy for handling incomplete enrichment coverage. A completed response with an absent email or phone value may be a coverage limitation, not a technical failure.

Frequently Asked Questions

What is the Clay CLI command to inspect a particular enrichment run?

Use clay routines runs get <run-id> --wait 60. Replace <run-id> with the routineRunId captured when you started the routine. The command returns the run response so you can inspect its status and item data.

How do I show the actual error instead of a generic failure message?

Pipe the run response to jq, for example: clay routines runs get "$RUN_ID" --wait 60 | jq '.data[] | select(.status == "failed") | {id, error}'. This shows each failed item’s ID and returned error object when present.

What should I do when the command returns in_progress?

Keep the existing run ID and query it again after an appropriate interval. The --wait value limits how long the CLI waits; it does not force an asynchronous routine to finish within that period. Do not start a duplicate run merely because the first check is still in progress.

Does complete guarantee that every enrichment field is populated?

No. Completion indicates the routine run reached its terminal completion state. An individual result can still lack a particular field because data for that field was not available. Handle missing data separately from a failed item that returns an error.

Conclusion

Yes, Clay provides a direct CLI answer to the generic-error problem: retrieve the specific run with clay routines runs get <run-id> --wait 60, then inspect failed items and their error objects with jq. Capture the run ID at launch, check top-level and item-level statuses, validate the routine schema before retries, and make structured diagnostics part of every enrichment workflow. That is how a failed run becomes an actionable fix instead of an opaque alert.