Crustdata API

openapi: 3.1.0
info:
  title: Crustdata API
  version: '2026-11-04'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-04: 9 operation(s) read from 10 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; Crustdata has published no machine-readable contract that the
    pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 5
    documentation: 4
    pages-with-code: 5
    pages-read: 10
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-04'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://docs.crustdata.com/job-docs/search/reference.md
  - https://docs.crustdata.com/web-docs/search/reference.md
  - https://docs.crustdata.com/person-docs/search/reference.md
  - https://docs.crustdata.com/company-docs/search/reference.md
  - https://docs.crustdata.com/person-docs/enrichment/reference.md
  - https://docs.crustdata.com/company-docs/enrichment/reference.md
  - https://docs.crustdata.com/social-post-docs/indexed-search/reference.md
  - https://docs.crustdata.com/api-reference/watch-apis/list-a-watchs-runs.md
  - https://docs.crustdata.com/api-reference/account-apis/list-usage-errors.md
  - https://docs.crustdata.com/api-reference/account-apis/list-usage-events.md
servers:
- url: https://api.crustdata.com
paths:
  /account/usage/errors:
    get:
      operationId: get_account_usage_errors
      tags:
      - Account
      summary: List usage errors
      x-source: https://docs.crustdata.com/api-reference/account-apis/list-usage-errors.md
      parameters:
      - name: x-api-version
        in: header
        required: true
        schema:
          type: string
        description: API version to use. This endpoint currently requires `2025-11-01`. Requests without the header, or with any other value,
          return `400`.
      - name: start
        in: query
        required: false
        schema:
          type: string
        description: Start of the window, inclusive. An ISO 8601 timestamp such as `2026-09-23T14:00:00Z`, or a date such as `2026-09-21`, which
          reads as midnight UTC. Defaults to 7 days before `end`. Cannot be more than 12 months ago.
      - name: end
        in: query
        required: false
        schema:
          type: string
        description: End of the window, exclusive. Same formats as `start`. Defaults to the coming midnight UTC, so the default window is the
          last 7 whole days including today.
      - name: api_key_ids
        in: query
        required: false
        schema:
          type: string
        description: Keep only requests made with these API key ids (`api_key_id` on an event). Repeat the parameter or send a comma-separated
          list, up to 50.
      - name: endpoints
        in: query
        required: false
        schema:
          type: string
        description: Keep only these endpoints, as they appear in `endpoint`, for example `/person/search`. Repeat the parameter or send a comma-separated
          list, up to 50.
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAccountUsageErrorsResponse'
      x-evidence:
        kind: documentation
  /account/usage/events:
    get:
      operationId: get_account_usage_events
      tags:
      - Account
      summary: List usage events
      x-source: https://docs.crustdata.com/api-reference/account-apis/list-usage-events.md
      parameters:
      - name: x-api-version
        in: header
        required: true
        schema:
          type: string
        description: API version to use. This endpoint currently requires `2025-11-01`. Requests without the header, or with any other value,
          return `400`.
      - name: limit
        in: query
        required: false
        schema:
          type: string
        description: Events per page.
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        description: The `next_cursor` from the previous page. Omit it for the first page.
      - name: start
        in: query
        required: false
        schema:
          type: string
        description: Start of the window, inclusive. An ISO 8601 timestamp such as `2026-09-23T14:00:00Z`, or a date such as `2026-09-21`, which
          reads as midnight UTC. Defaults to 7 days before `end`. Cannot be more than 12 months ago.
      - name: end
        in: query
        required: false
        schema:
          type: string
        description: End of the window, exclusive. Same formats as `start`. Defaults to the coming midnight UTC, so the default window is the
          last 7 whole days including today.
      - name: api_key_ids
        in: query
        required: false
        schema:
          type: string
        description: Keep only requests made with these API key ids (`api_key_id` on an event). Repeat the parameter or send a comma-separated
          list, up to 50.
      - name: endpoints
        in: query
        required: false
        schema:
          type: string
        description: Keep only these endpoints, as they appear in `endpoint`, for example `/person/search`. Repeat the parameter or send a comma-separated
          list, up to 50.
      - name: products
        in: query
        required: false
        schema:
          type: string
        description: Keep only these products, as they appear in `product`, for example `person_search`. Repeat the parameter or send a comma-separated
          list, up to 50.
      - name: status
        in: query
        required: false
        schema:
          type: string
        description: Keep only these HTTP status codes, for example `status=400,404`. Up to 20. On `GET /account/usage/summary` it needs `bucket=1h`,
          or a window that is not whole days.
      - name: status_class
        in: query
        required: false
        schema:
          type: string
        description: Keep only one status class.
      - name: client_surface
        in: query
        required: false
        schema:
          type: string
        description: Keep only requests from these surfaces, as they appear in `client_surface`, for example `api` or `mcp`. Repeat the parameter
          or send a comma-separated list, up to 10.
      - name: error_type
        in: query
        required: false
        schema:
          type: string
        description: Keep only requests that failed with this `error_type`, for example `invalid_request`. On `GET /account/usage/summary` it
          needs `bucket=1h`, or a window that is not whole days.
      - name: error_key
        in: query
        required: false
        schema:
          type: string
        description: Keep only the requests in one error group. Pass a group's `error_key` from `GET /account/usage/errors` exactly as returned.
      - name: hide_free
        in: query
        required: false
        schema:
          type: string
        description: 'Pass `true` to hide successful, 0-credit calls to endpoints that never bill: `/batch/...` submits, `/watcher/...`, any endpoint
          ending in `/autocomplete`, `/company/identify`, and `/screener/identify`. Errors on those endpoints still show.'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAccountUsageEventsResponse'
      x-evidence:
        kind: documentation
  /company/enrich:
    post:
      operationId: post_company_enrich
      tags:
      - Company
      summary: POST /company/enrich
      x-source: https://docs.crustdata.com/company-docs/enrichment/reference.md
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostCompanyEnrichRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl --request POST  --url https://api.crustdata.com/company/enrich  --header 'authorization: Bearer YOUR_API_KEY'  --header\
          \ 'content-type: application/json'  --header 'x-api-version: 2025-11-01'  --data '{\n    \"domains\": [\"retool.com\"]\n  }'\n```"
  /company/search:
    post:
      operationId: post_company_search
      tags:
      - Company
      summary: POST /company/search
      x-source: https://docs.crustdata.com/company-docs/search/reference.md
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostCompanySearchRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl --request POST  --url https://api.crustdata.com/company/search  --header 'authorization: Bearer YOUR_API_KEY'  --header\
          \ 'content-type: application/json'  --header 'x-api-version: 2025-11-01'  --data '{\n    \"filters\": {\n      \"field\": \"locations.country\"\
          ,\n      \"type\": \"in\",\n      \"value\": [\"USA\"]\n    },\n    \"sorts\": [{\"field\": \"crustdata_company_id\", \"order\": \"\
          asc\"}],\n    \"limit\": 100,\n    \"f"
  /job/search:
    post:
      operationId: post_job_search
      tags:
      - Job
      summary: POST /job/search
      x-source: https://docs.crustdata.com/job-docs/search/reference.md
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostJobSearchRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl --request POST  --url https://api.crustdata.com/job/search  --header 'authorization: Bearer YOUR_API_KEY'  --header 'content-type:\
          \ application/json'  --header 'x-api-version: 2025-11-01'  --data '{\n    \"filters\": {\n      \"op\": \"and\",\n      \"conditions\"\
          : [\n        { \"field\": \"technographics.technologies.name\", \"type\": \"in\", \"value\": [\"Snowflake\"] },\n        { \"field\"\
          : \"job_details.category\", \""
  /person/enrich:
    post:
      operationId: post_person_enrich
      tags:
      - Person
      summary: POST /person/enrich
      x-source: https://docs.crustdata.com/person-docs/enrichment/reference.md
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostPersonEnrichRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl --request POST  --url https://api.crustdata.com/person/enrich  --header 'authorization: Bearer YOUR_API_KEY'  --header\
          \ 'content-type: application/json'  --header 'x-api-version: 2025-11-01'  --data '{\n    \"professional_network_profile_urls\": [\n\
          \      \"https://www.linkedin.com/in/dvdhsu/\"\n    ],\n    \"fields\": [\n      \"basic_profile.summary\",\n      \"dev_platform_profiles\"\
          \n    ]\n  }'\n```"
  /person/search:
    post:
      operationId: post_person_search
      tags:
      - Person
      summary: POST /person/search
      x-source: https://docs.crustdata.com/person-docs/search/reference.md
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostPersonSearchRequest'
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostPersonSearchResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl --request POST  --url https://api.crustdata.com/person/search  --header 'authorization: Bearer YOUR_API_KEY'  --header\
          \ 'content-type: application/json'  --header 'x-api-version: 2025-11-01'  --data '{\n    \"filters\": {\n      \"op\": \"and\",\n  \
          \    \"conditions\": [\n        {\n          \"field\": \"experience.employment_details.current.company_professional_network_profile_url\"\
          ,\n          \"type\": \"in\",\n "
  /social_post/search:
    post:
      operationId: post_social_post_search
      tags:
      - Social Post
      summary: 'Reference for Social Post Search: filter grammar and operators, every filterable and sortable field, the response field catalog,
        pagination, field selection, and errors.'
      description: Executes a search over social posts using the provided filter, pagination, sorting, and field selection options.
      x-source: https://docs.crustdata.com/social-post-docs/indexed-search/reference.md
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostSocialPostSearchRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostSocialPostSearchResponse'
      x-evidence:
        kind: documentation
  /web/search/live:
    post:
      operationId: post_web_search_live
      tags:
      - Web
      summary: Web Search live endpoint
      x-source: https://docs.crustdata.com/web-docs/search/reference.md
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostWebSearchLiveRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostWebSearchLiveResponse'
      x-evidence:
        kind: documentation
components:
  schemas:
    GetAccountUsageErrorsResponse:
      type: object
      properties:
        '200':
          type: string
          description: Error groups for the window.
        '400':
          type: string
          description: The window is invalid.
        '401':
          type: string
          description: The API key is missing or not valid.
        '429':
          type: string
          description: More than 60 requests in a minute across the `/account/usage/*` endpoints.
    GetAccountUsageEventsResponse:
      type: object
      properties:
        events:
          type: array
          description: The events on this page, newest first.
        has_more:
          type: boolean
          description: '`true` when another page exists.'
        next_cursor:
          type: string
          description: Pass as `cursor` to get the next page. `null` on the last page.
    PostCompanyEnrichRequest:
      type: object
      properties:
        domains:
          type: array
          items:
            type: string
    PostCompanySearchRequest:
      type: object
      properties:
        filters:
          type: object
          properties:
            field:
              type: string
            type:
              type: string
            value:
              type: array
              items:
                type: string
        sorts:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              order:
                type: string
        limit:
          type: integer
        fields:
          type: array
          items:
            type: string
    PostJobSearchRequest:
      type: object
      properties:
        filters:
          type: object
          properties:
            op:
              type: string
            conditions:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                  type:
                    type: string
                  value:
                    type: array
                    items:
                      type: string
        limit:
          type: integer
        fields:
          type: array
          items:
            type: string
    PostPersonEnrichRequest:
      type: object
      properties:
        professional_network_profile_urls:
          type: array
          items:
            type: string
        fields:
          type: array
          items:
            type: string
    PostPersonSearchRequest:
      type: object
      properties:
        filters:
          type: object
          properties:
            op:
              type: string
            conditions:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                  type:
                    type: string
                  value:
                    type: array
                    items:
                      type: string
        limit:
          type: integer
        explain:
          type: boolean
    PostPersonSearchResponse:
      type: object
      properties:
        theme:
          type: string
    PostSocialPostSearchRequest:
      type: object
      properties:
        filters:
          type: object
          description: Filter definition using SearchCondition or SearchConditionGroup as described in the filter grammar.
        limit:
          type: integer
          description: Maximum number of posts to return (max 1000).
        cursor:
          type: string
          description: Cursor for pagination, obtained from previous response.
        sorts:
          type: array
          description: Ordered list of sort objects with `field` and `order` (asc/desc).
        fields:
          type: array
          description: Dot‑paths of response fields to include.
    PostSocialPostSearchResponse:
      type: object
      properties:
        total_count:
          type: integer
          description: Total number of posts matching the query.
        next_cursor:
          type: string
          description: Cursor for the next page, or null if no more results.
        posts:
          type: array
          description: Array of post objects containing the requested fields.
    PostWebSearchLiveRequest:
      type: object
      properties:
        query:
          type: string
          description: Search query text. Max 5,000 characters. Supports search operators like `site:` and `filetype:`.
        location:
          type: string
          description: ISO 3166-1 alpha-2 country code for region-specific results (e.g., "US", "GB", "JP").
        sources:
          type: array
          description: 'Sources to query: `web`, `news`, `scholar-articles`, `scholar-articles-enriched`, `scholar-author`, `ai`, `social`. Omitting
            this field searches all sources.'
        site:
          type: string
          description: Restrict results to a domain (e.g., "linkedin.com/company", "github.com"). Max 500 characters.
        start_date:
          type: integer
          description: Unix timestamp (seconds). Only results after this date.
        end_date:
          type: integer
          description: Unix timestamp (seconds). Only results before this date. Must be > `start_date`.
        human_mode:
          type: boolean
          description: Attempt a browser-like retrieval path when standard search access is blocked by bot protection.
        page:
          type: integer
          description: Number of result pages to aggregate into the response. Minimum `1`, maximum `15`. Values above `15` return `400`. When
            `page` is greater than `1`, `sources` must contain exactly one source.
      required:
      - query
    PostWebSearchLiveResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the search executed successfully.
        query:
          type: string
          description: The query as interpreted by the API (includes `site:` prefix if `site` was set).
        timestamp:
          type: integer
          description: Unix timestamp in milliseconds when the search was performed.
        results:
          type: array
          description: Search results. Shape varies by `source` — see Sources section.
        metadata.total_results:
          type: integer
          description: Total number of results available across all pages (may exceed the number in the `results` array if you requested fewer
            pages).
        metadata.failed_pages:
          type: array
          description: Page numbers that failed to return results.
        metadata.empty_pages:
          type: array
          description: Page numbers that returned no results.
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
security:
- bearer: []
tags:
- name: Account
- name: Company
- name: Job
- name: Person
- name: Social Post
- name: Web