Response object

The following API operations return a response of type PipesResponse:

• POST https://api.pipe0.com/v1/pipes/run (create an enrichment task)
• GET https://api.pipe0.com/v1/pipes/check/{run_id} (check the processing state)
• POST https://api.pipe0.com/v1/pipes/run/sync (create an enrichment task and return the result)

Responses are designed for building rich data tables like Clay, node-based workflow builders like Zapier, and plain automation code (think n8n as code).

By default, responses contain enriched data only. Enable widgets and field definitions for additional metadata, for example which providers were used in a waterfall.

The raw response object

Response object properties

id

The task id. During and after processing you can use this id to look up your processing result with GET /v1/pipes/check/{run_id}. Finished tasks are deleted 21 days after they were created.

status

The status of the response object.

Status 'pending'

Your request has been validated and an enrichment task has been created. Processing has not yet begun.

Status 'processing'

Your request has been validated and processing has begun. During processing, the status of your record fields is continuously updated.

Status 'completed'

Processing has finished without global errors. Individual fields may still have failed to process.

Status 'failed'

Pipeline validation or processing has failed. See the global errors property for more information on why the failure occurred.

order

We transform the list of input data into an object called records. The records object has keys that match the ids of your input data, but it does not preserve the order of your input.

The order property preserves it for you: an ordered list of input data ids.

field_definitions

Metadata for all fields that exist in your pipeline.

Think of each input object as a row of a table. If input data are the rows, then field_definitions are the columns.

The field_definitions object contains all fields that exist in your pipeline. This includes pipe output fields and fields derived from input objects. The keys are field names, the values field properties.

errors

Global task errors. If your response contains errors at the top level, your task failed. Use this error array to understand why. Individual fields can fail too; in that case, the field contains a local error.

records

Each input object is transformed into a record object during processing.

record.id

The id you provided in your input object.

record.fields

If your original request contained an input array of the shape [{id: 1, foo: "bar"}, {id: 2, "bar": "baz"}], all output records will have the fields id, foo, and bar.

The fields are normalized: all output records have the same fields. If any input object contains a property, it is added to all output records.

In addition to fields derived from input objects, record.fields contains pipe output fields.

It is guaranteed that field_definitions and record.fields have the same keys.

record.field.value

The value of the field. If the value was provided as part of your input data it is copied over. If the value was generated from an enrichment operation, it is added.

record.field.status

The status of the field. Possible values are completed, failed, pending, queued, processing, skipped, or no_result. The status is no_result if processing completed without yielding a meaningful result, failed if the pipe failed due to errors, and skipped if processing was skipped due to an unmet condition or missing input.

record.field.type

The type of the provided or generated value. Possible values are string, number, boolean, json, or unknown. The type is unknown only when pipe0 has nothing to infer it from: the field is not in the field catalog, no input object provided a value, and no pipe outputs it. Catalog fields like name keep their catalog type even when every value is null.

record.field.reason

Of type null | {code: string; summary: string; message: string}. Non-null whenever the status is failed, no_result, or skipped, and tells you why: a provider error, an unmet run_if condition (PipeConditionUnmet), or a missing required input (RequirementUnmet).

record.field.claimed_by

Each field is assigned to an entity that is responsible for resolving it. Resolvers can be input data or pipes. A pipe "claims" each field it is responsible for. A pipe claiming a field does not mean it will resolve it: if your input object already contains a valid value, the field is claimed by a pipe but resolved by input.

Use this field to render fields as columns ordered by pipe.

record.field.resolved_by

Tells you where the field's current state came from. resolved_by.ref is one of:

• a pipe_id: the value was produced by that pipe.
• "input": the value was copied over from your input data.
• "system": pipe0 set the state, for example when it queues a field for reprocessing or marks it failed.
• null: nothing has resolved the field yet.

Together with claimed_by, this gives you full provenance: a field claimed by a pipe but resolved by input means your input already contained a valid value and the pipe did not run for it.

record.field.format

A more specific format for the value, or null. Examples: email, url, profile_url, date, text, int. Formats drive input sanitation and validation. See input sanitation.

record.field.widgets

Structured metadata for rendering rich UIs, present when you set config.widgets.enabled to true (default false). For waterfall pipes, widgets.waterfall lists attempted_providers, available_providers, and the successful_provider, so you can show which provider found the value.