Read an agent search

curl --request GET \
  --url https://api.crustdata.com/agent/searches/{search_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'x-api-version: <x-api-version>'

import requests

url = "https://api.crustdata.com/agent/searches/{search_id}"

headers = {
    "x-api-version": "<x-api-version>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'x-api-version': '<x-api-version>', Authorization: 'Bearer <token>'}
};

fetch('https://api.crustdata.com/agent/searches/{search_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "search_id": "1318-07fcae93f67c961a96c8758766b2fea1",
  "query": "The founders of Crustdata",
  "state": "succeeded",
  "created_at": "2026-11-13T11:32:26.860998+00:00",
  "output": {
    "note": null,
    "reason": null,
    "person": {
      "constraints": [
        {
          "id": "c1",
          "text": "Founded Crustdata.",
          "importance": "hard"
        }
      ],
      "columns": [
        {
          "key": "name",
          "label": "Name",
          "field": "basic_profile.name"
        },
        {
          "key": "profile_url",
          "label": "Profile URL",
          "field": "social_handles.professional_network_identifier.profile_url"
        },
        {
          "key": "basic_profile_headline",
          "label": "Headline",
          "field": "basic_profile.headline"
        }
      ],
      "rows": [
        {
          "id": 1068035,
          "values": {
            "basic_profile_headline": "Co-founder at Crustdata (YC F24) | Infra for building AI employees",
            "name": "Abhilash Chowdhary",
            "profile_url": "https://www.linkedin.com/in/abhilashchowdhary"
          },
          "constraints": [
            {
              "constraint_id": "c1",
              "assessment": "satisfied",
              "evidence": "Headline identifies him as Crustdata co-founder, and current employer title is Co-Founder & CEO.",
              "fields": [
                "basic_profile.headline"
              ]
            }
          ]
        },
        {
          "id": 1148585,
          "values": {
            "basic_profile_headline": "Co-Founder at Crustdata (YC F24) | Building most accurate search engine for people search",
            "name": "Manmohit Grewal",
            "profile_url": "https://www.linkedin.com/in/manmohitgrewal"
          },
          "constraints": [
            {
              "constraint_id": "c1",
              "assessment": "satisfied",
              "evidence": "Headline and current role identify him as a Crustdata co-founder.",
              "fields": [
                "basic_profile.headline"
              ]
            }
          ]
        },
        {
          "id": 402126,
          "values": {
            "basic_profile_headline": "Co-founder at Crustdata (YC F24) | Real-time B2B data for AI Agents",
            "name": "Chris Pisarski",
            "profile_url": "https://www.linkedin.com/in/chris-pisarski"
          },
          "constraints": [
            {
              "constraint_id": "c1",
              "assessment": "satisfied",
              "evidence": "Headline identifies him as co-founder, and his summary says he is building Crustdata.",
              "fields": [
                "basic_profile.headline",
                "professional_network.summary"
              ]
            }
          ]
        }
      ]
    }
  },
  "credits_used": {
    "agent_cost": 0.66,
    "search_cost": 0.1385,
    "enrich_cost": 0,
    "contact_cost": 0,
    "total_cost": 0.7985
  },
  "error": null
}

Read a search

Read a search: its state, and its answer when it succeeded. Poll this route every few seconds until state is succeeded, failed or cancelled.

The first read after the search ends charges it. That read carries the charge in X-Credits-Used and in credits_used. Every later read returns X-Credits-Used: 0 and shows the same credits_used. A search that you streamed to its end was charged by the stream, so its reads all return X-Credits-Used: 0.

The answer is in output, under one entity key: person, company or job. The agent picks the columns. The body shows each column that your account may receive, plus the contact columns, which every account receives.

Default rate-limit is 300 requests per minute, shared by the read, events, and cancel routes.

GET

https://api.crustdata.com

agent

searches

{search_id}

Read an agent search

curl --request GET \
  --url https://api.crustdata.com/agent/searches/{search_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'x-api-version: <x-api-version>'

import requests

url = "https://api.crustdata.com/agent/searches/{search_id}"

headers = {
    "x-api-version": "<x-api-version>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'x-api-version': '<x-api-version>', Authorization: 'Bearer <token>'}
};

fetch('https://api.crustdata.com/agent/searches/{search_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "search_id": "1318-07fcae93f67c961a96c8758766b2fea1",
  "query": "The founders of Crustdata",
  "state": "succeeded",
  "created_at": "2026-11-13T11:32:26.860998+00:00",
  "output": {
    "note": null,
    "reason": null,
    "person": {
      "constraints": [
        {
          "id": "c1",
          "text": "Founded Crustdata.",
          "importance": "hard"
        }
      ],
      "columns": [
        {
          "key": "name",
          "label": "Name",
          "field": "basic_profile.name"
        },
        {
          "key": "profile_url",
          "label": "Profile URL",
          "field": "social_handles.professional_network_identifier.profile_url"
        },
        {
          "key": "basic_profile_headline",
          "label": "Headline",
          "field": "basic_profile.headline"
        }
      ],
      "rows": [
        {
          "id": 1068035,
          "values": {
            "basic_profile_headline": "Co-founder at Crustdata (YC F24) | Infra for building AI employees",
            "name": "Abhilash Chowdhary",
            "profile_url": "https://www.linkedin.com/in/abhilashchowdhary"
          },
          "constraints": [
            {
              "constraint_id": "c1",
              "assessment": "satisfied",
              "evidence": "Headline identifies him as Crustdata co-founder, and current employer title is Co-Founder & CEO.",
              "fields": [
                "basic_profile.headline"
              ]
            }
          ]
        },
        {
          "id": 1148585,
          "values": {
            "basic_profile_headline": "Co-Founder at Crustdata (YC F24) | Building most accurate search engine for people search",
            "name": "Manmohit Grewal",
            "profile_url": "https://www.linkedin.com/in/manmohitgrewal"
          },
          "constraints": [
            {
              "constraint_id": "c1",
              "assessment": "satisfied",
              "evidence": "Headline and current role identify him as a Crustdata co-founder.",
              "fields": [
                "basic_profile.headline"
              ]
            }
          ]
        },
        {
          "id": 402126,
          "values": {
            "basic_profile_headline": "Co-founder at Crustdata (YC F24) | Real-time B2B data for AI Agents",
            "name": "Chris Pisarski",
            "profile_url": "https://www.linkedin.com/in/chris-pisarski"
          },
          "constraints": [
            {
              "constraint_id": "c1",
              "assessment": "satisfied",
              "evidence": "Headline identifies him as co-founder, and his summary says he is building Crustdata.",
              "fields": [
                "basic_profile.headline",
                "professional_network.summary"
              ]
            }
          ]
        }
      ]
    }
  },
  "credits_used": {
    "agent_cost": 0.66,
    "search_cost": 0.1385,
    "enrich_cost": 0,
    "contact_cost": 0,
    "total_cost": 0.7985
  },
  "error": null
}

Authorizations

Authorization

string

header

required

API key passed as a Bearer token in the Authorization header.

Headers

x-api-version

enum<string>

default:2025-11-01

required

API version to use. This endpoint currently requires 2025-11-01.

Available options:

2025-11-01

Example:

"2025-11-01"

Path Parameters

search_id

string

required

The search_id that the start returned.

Example:

"1318-07fcae93f67c961a96c8758766b2fea1"

Response

The search.

A search, with its answer when it succeeded. Ignore a key you do not know, because new keys can come.

search_id

string

required

The id that the start returned.

Example:

"1318-07fcae93f67c961a96c8758766b2fea1"

query

string

required

The question as you sent it.

Example:

"The founders of Crustdata"

state

enum<string>

required

The state of a search. succeeded, failed and cancelled are end states. Every search in progress is running today. queued is not returned today; a later release adds it for a search that waits in a queue. Treat every state that is not an end state as in progress. This enum is closed.

Available options:

queued,

running,

succeeded,

failed,

cancelled

Example:

"running"

created_at

string<date-time>

required

When the search started.

Example:

"2026-11-13T11:32:26.860998+00:00"

output

object | null

required

The answer. It is set only when state is succeeded.

Show child attributes

Example:

{
  "note": null,
  "reason": null,
  "company": {
    "constraints": [
      {
        "id": "c2",
        "text": "The company is headquartered in Berlin.",
        "importance": "hard"
      }
    ],
    "columns": [
      {
        "key": "name",
        "label": "Name",
        "field": "basic_info.name"
      }
    ],
    "rows": [
      {
        "id": 675954,
        "values": { "name": "Billie" },
        "constraints": [
          {
            "constraint_id": "c2",
            "assessment": "satisfied",
            "evidence": "Headquarters are listed in Berlin, Germany.",
            "fields": ["locations.headquarters"]
          }
        ]
      }
    ]
  }
}

credits_used

object

required

The charge, in credits. It grows with the effort of the search. Every key is 0 until the search is charged. A search that finds nothing, fails, or is cancelled costs 0. total_cost is the sum of the 4 parts.

Show child attributes

error

object | null

required

Why the search failed. It is set only when state is failed.

Show child attributes

Example:

{
  "type": "internal_error",
  "message": "The search did not finish in time. A narrower query may finish.",
  "metadata": [{ "retryable": true }]
}

API Reference

Company API

Person API

Web API

Job API

Watch API

Social Post API

Agent Search API

Batch API

Account API

Read a search

Authorizations

Headers

Path Parameters

Response