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)

Learn more about the difference between sync and async operations.

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": {
		"config": {
			"filters": {
				"current_job_titles": ["Software Engineer", "Developer"]
			},
			"pagination": {
				"limit": 100,
				"cursor": "H4sIAMaPrWkC..."
			},
			"output_fields": {
				"name": { "alias": "", "enabled": true },
				"job_title": { "alias": "", "enabled": true },
				"profile_url": { "alias": "", "enabled": true }
			}
		},
		"search_id": "people:profiles:crustdata@2"
	},
	"results": [
		{
			"name": {
				"ui": {},
				"type": "string",
				"value": "Gayle Pouros",
				"format": "text",
				"status": "completed",
				"resolved_by": {
					"ref": "people:profiles:crustdata@2",
					"environment": "production",
					"config_hash": "…",
					"input_hash": "…"
				}
			},
			"job_title": {
				"ui": {},
				"type": "string",
				"value": "Product Intranet Manager",
				"format": "text",
				"status": "completed"
			}
		},
		{
			"name": {
				"ui": {},
				"type": "string",
				"value": "Mae Feest",
				"format": "text",
				"status": "completed"
			},
			"job_title": {
				"ui": {},
				"type": "string",
				"value": "Dynamic Data Liaison",
				"format": "text",
				"status": "completed"
			}
		}
	]
}

Response Properties

id

This is the task id. You can use this id to look up your processing result during and after processing. We store tasks for up to 15 days after processing is completed.

status

The status of the response object.

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. 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.

pagination_type

The type of pagination used. Currently supports cursor.

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.

next_page.search_id

The search id to use for the next page request.

next_page.config

The config object pre-filled with the cursor and filters for the next page.

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 (e.g. 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 (e.g. 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 across searches. 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:

result.field.value

The value of the field.

result.field.status

The status of the field. Possible values include completed, no_result, and failed.

result.field.type

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

result.field.format

An optional value format hint (e.g. email, url), or null.

result.field.resolved_by

Provenance of the value: { ref, environment, config_hash, input_hash }. ref identifies the operation that produced the value, or input for values that were not produced by a search or pipe. 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 (e.g. provider logos). See config.widgets.enabled in the request payload.