Response object

The following API operations return a response of type SearchResponse:

• POST https://api.pipe0.com/v1/search/run (create a search task)
• GET https://api.pipe0.com/v1/search/check/{run_id} (check the processing state of a search task)
• POST https://api.pipe0.com/v1/search/run/sync (run a search task synchronously)

Both run endpoints accept the same payload; see sync vs async for the trade-offs.

Full response object

{
	"id": "jyg5w5p7unhcufkp8f7z5za8",
	"status": "completed",
	"search_id": "people:profiles:crustdata@2",
	"organization_id": "v417gjrw51ft55f85ueeqgpt",
	"errors": [],
	"total_pages": 2764,
	"pagination_type": "cursor",
	"next_page": {
		"search_id": "people:profiles:crustdata@2",
		"config": {
			"filters": {
				"current_job_titles": { "include": ["Software Engineer", "Developer"] }
			},
			"limit": 100,
			"cursor": "H4sIAMaPrWkC..."
		},
		"connector": null
	},
	"results": [
		{
			"name": {
				"type": "string",
				"value": "Gayle Pouros",
				"format": "text",
				"status": "completed",
				"resolved_by": {
					"ref": "input",
					"environment": "production",
					"config_hash": "…",
					"input_hash": "…"
				}
			},
			"job_title": {
				"type": "string",
				"value": "Product Intranet Manager",
				"format": "text",
				"status": "completed"
			}
		},
		{
			"name": {
				"type": "string",
				"value": "Mae Feest",
				"format": "text",
				"status": "completed"
			},
			"job_title": {
				"type": "string",
				"value": "Dynamic Data Liaison",
				"format": "text",
				"status": "completed"
			}
		}
	]
}

Response Properties

id

The task id. You can use this id to look up your processing result during and after processing with GET /v1/search/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 a search task has been created. Processing has not yet begun. This is the status POST /v1/search/run returns.

Status 'processing'

Your search request is being processed.

Status 'completed'

Processing has finished without errors.

Status 'failed'

Processing has failed. See the errors array for more information on why the failure occurred.

search_id

The search id that was used for this request.

organization_id

The organization that owns this search task.

errors[]

An array of errors of the shape {code, message, path?}. Empty when the search completed successfully. Contains error details when the search has failed.

total_pages

The total number of pages available for this search result, or null. Computed from the provider's total result count divided by your page limit.

pagination_type

How the underlying provider paginates: cursor or page_number, or null. You don't need to branch on this; next_page handles both. See Pagination.

next_page

Contains the configuration needed to fetch the next page of results. Use this object as the body of a subsequent request to paginate through results. This field is null when there are no more pages. See Pagination.

next_page.search_id

The search id to use for the next page request.

next_page.config

The config object pre-filled with your filters plus the updated cursor or page_number for the next page. These are plain keys on config, the same place you set limit in your original request.

field_definitions

A map describing every column the search returns. This field is only present when you opt in via config.field_definitions.enabled in the request. When omitted from the request (the default), the response contains no field_definitions and existing clients are unaffected.

field_definitions gives you a uniform, self-describing way to learn a search's columns, for example to build a results table before any rows arrive. It is populated for every search, not just dynamic ones:

• Static searches derive their columns from the catalog output fields. The column set is fixed and known ahead of time.
• Dynamic searches (for example sheet:rows@1) supply their columns from the run. The column set equals the underlying data source (for sheet:rows@1, the sheet's columns) and can vary per run.

The keys are column names and the values describe each column:

{
	"email": { "type": "string", "label": "Email", "format": "email", "json_metadata": null },
	"company": { "type": "string", "label": "Company", "format": null, "json_metadata": null },
	"score": { "type": "number", "label": "Lead score", "format": null, "json_metadata": null }
}

• type: one of string, number, boolean, json, or unknown.
• label: an optional human-readable column name.
• format: an optional value format hint (for example email, url, date).
• json_metadata: for json columns, an optional { schema, example_value } descriptor; null otherwise.

results[]

A list of search results. The fields of each object are normalized: every row carries every column, and a column the provider didn't return for a row is null. You can use the results as is or use them as input for a pipes request.

Each result is an object keyed by column name. The value of each column is a field object (or null):

result.field.value

The value of the field.

result.field.status

The status of the field. Fresh search output is always completed or no_result. Dynamic reads like sheet:rows@1 with include_metadata: true pass stored cell statuses through unchanged, so any field status can appear: completed, failed, pending, queued, processing, skipped, or no_result.

result.field.type

The type of the value. One of string, number, boolean, json, or unknown.

result.field.format

An optional value format hint (for example email, url), or null.

result.field.resolved_by

Provenance of the value: { ref, environment, config_hash, input_hash }. A search never writes its own id into ref. Values a search fetches are stamped ref: "input", because a search mints input records; only pipes appear as producers. For dynamic reads like sheet:rows@1 the provenance is passed through as stored: a cell that was originally produced by a pipe keeps that pipe's ref (the search is a reader, not the producer).

result.field.widgets

Additional metadata used to render the value (for example provider logos). See config.widgets.enabled in the request payload.