> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crustdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List your searches

> List the searches of your account, newest first, one page at a time. Each entry has
the `search_id`, the `query`, the time the search started, and its `credits_used`.
An entry has no state and no answer. Read the search with
`GET /agent/searches/{search_id}` for those.

A page has at most `limit` entries. When `has_more` is `true`, send `next_cursor`
as `cursor` to get the next page. On the last page, `next_cursor` is `null`.

Every key of `credits_used` is 0 until the search is charged. The list costs
nothing and returns `X-Credits-Used: 0`.

<Note>
    Default `rate-limit` is 300 requests per minute. The list has its own budget, apart from the read, events, and cancel routes.
</Note>




## OpenAPI

````yaml /openapi-specs/2025-11-01/agent_search.yaml get /agent/searches
openapi: 3.0.3
info:
  title: Agent Search API
  version: '2025-11-01'
  description: >
    The Agent Search API (beta) takes a question in plain words and returns the
    matching

    people, companies or jobs, each with the reasons it matches. You send the
    question to `POST /agent/searches`. An agent searches the

    Crustdata datasets in the background, picks the columns of the answer, and
    checks each

    row against the requirements it read in your question.


    A search runs for tens of seconds to a few minutes. Read it with

    `GET /agent/searches/{search_id}` until `state` is `succeeded`, `failed` or
    `cancelled`,

    or stream its events with `Accept: text/event-stream`.


    All requests require a valid API key passed via the `Authorization` header
    as a Bearer

    token and an `x-api-version` header set to `2025-11-01`.
servers:
  - url: https://api.crustdata.com
    description: Production API server
security:
  - bearerAuth: []
tags:
  - name: Agent Search APIs
    description: Start, list, read, stream and cancel agent searches.
paths:
  /agent/searches:
    get:
      tags:
        - Agent Search APIs
      summary: List your agent searches
      description: >
        List the searches of your account, newest first, one page at a time.
        Each entry has

        the `search_id`, the `query`, the time the search started, and its
        `credits_used`.

        An entry has no state and no answer. Read the search with

        `GET /agent/searches/{search_id}` for those.


        A page has at most `limit` entries. When `has_more` is `true`, send
        `next_cursor`

        as `cursor` to get the next page. On the last page, `next_cursor` is
        `null`.


        Every key of `credits_used` is 0 until the search is charged. The list
        costs

        nothing and returns `X-Credits-Used: 0`.


        <Note>
            Default `rate-limit` is 300 requests per minute. The list has its own budget, apart from the read, events, and cancel routes.
        </Note>
      operationId: listAgentSearches
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - name: limit
          in: query
          required: false
          description: The most entries on one page, from 1 to 100.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: cursor
          in: query
          required: false
          description: >-
            The `next_cursor` of the page before. Leave it out for the first
            page.
          schema:
            type: string
            example: '5431'
      responses:
        '200':
          headers:
            X-Credits-Used:
              $ref: '#/components/headers/XCreditsUsed'
          description: One page of your searches.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentSearchList'
              examples:
                first_page:
                  summary: The first page, with limit=2
                  value:
                    searches:
                      - search_id: 1318-9e2964567a774d25bc657bc941c3ed17
                        query: >-
                          Find 5 data engineers who work at Databricks in
                          Seattle
                        created_at: '2026-11-19T22:24:00.988772+00:00'
                        credits_used:
                          agent_cost: 1.53
                          search_cost: 0.26
                          enrich_cost: 0
                          contact_cost: 0
                          total_cost: 1.79
                      - search_id: 1318-8d00448d0d0d4a46b6d126355ea7471a
                        query: >-
                          find one person in San Francisco who left
                          Google/Meta/Apple/Amazon/Microsoft in last 6 months
                          for a startup, with work email
                        created_at: '2026-11-19T22:20:17.105828+00:00'
                        credits_used:
                          agent_cost: 0.65
                          search_cost: 0.34
                          enrich_cost: 0
                          contact_cost: 0.25
                          total_cost: 1.24
                    next_cursor: '5431'
                    has_more: true
        '400':
          headers:
            X-Credits-Used:
              $ref: '#/components/headers/XCreditsUsed'
          description: >-
            A query key that the list does not take, or a `limit` or `cursor`
            that is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                other_key:
                  summary: A query key other than limit and cursor
                  value:
                    error:
                      type: invalid_request
                      message: The list takes only `limit` and `cursor` as query keys.
                      metadata: []
                bad_limit:
                  summary: A limit that is empty, not a number, or out of range
                  value:
                    error:
                      type: invalid_request
                      message: '`limit` must be an integer from 1 to 100.'
                      metadata: []
                bad_cursor:
                  summary: A cursor that is empty or not a next_cursor
                  value:
                    error:
                      type: invalid_request
                      message: '`cursor` must be the `next_cursor` of the previous page.'
                      metadata: []
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          description: >-
            More than 300 requests to the list in one minute. This `429` has no
            `Retry-After` header: wait for the seconds in `X-RateLimit-Reset`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                rate_limit:
                  summary: The rate limit is used up
                  value:
                    error:
                      type: rate_limit_error
                      message: >-
                        Rate limit exceeded for this endpoint. Please write to
                        gtm@crustdata.co.
                      metadata: []
components:
  parameters:
    ApiVersion:
      name: x-api-version
      in: header
      required: true
      schema:
        type: string
        enum:
          - '2025-11-01'
        default: '2025-11-01'
        example: '2025-11-01'
      description: API version to use. This endpoint currently requires `2025-11-01`.
  headers:
    XCreditsUsed:
      description: >-
        Exact credits this request deducted, as a decimal string (for example
        `0.92`). On these routes, only the first read after a search ends
        carries a value above `0`. Responses generated before a request reaches
        the API, such as rate-limit `429`s, do not carry it.
      schema:
        type: string
        example: '0.92'
  schemas:
    AgentSearchList:
      type: object
      description: One page of your searches, newest first.
      required:
        - searches
        - next_cursor
        - has_more
      properties:
        searches:
          type: array
          items:
            $ref: '#/components/schemas/AgentSearchListEntry'
        next_cursor:
          type: string
          nullable: true
          description: >-
            Send it as `cursor` to get the next page. It is `null` on the last
            page.
          example: '5431'
        has_more:
          type: boolean
          description: '`true` when another page follows.'
          example: true
    ErrorResponse:
      type: object
      description: >-
        The body of almost every error response. A `405` and a `404` on an
        unknown path have another body.
      required:
        - error
      properties:
        error:
          type: object
          required:
            - type
            - message
            - metadata
          properties:
            type:
              type: string
              example: invalid_request
            message:
              type: string
            metadata:
              type: array
              description: >-
                Empty, or `[{"retryable": true, "retry_after_seconds": N}]` on a
                error that can clear if you try again later.
              items:
                type: object
                properties:
                  retryable:
                    type: boolean
                  retry_after_seconds:
                    type: integer
    AgentSearchListEntry:
      type: object
      description: One search in the list. It has no state and no answer.
      required:
        - search_id
        - query
        - created_at
        - credits_used
      properties:
        search_id:
          type: string
          example: 1318-9e2964567a774d25bc657bc941c3ed17
        query:
          type: string
          example: Find 5 data engineers who work at Databricks in Seattle
        created_at:
          type: string
          format: date-time
          example: '2026-11-19T22:24:00.988772+00:00'
        credits_used:
          $ref: '#/components/schemas/AgentCreditsUsed'
    AgentCreditsUsed:
      type: object
      description: >-
        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. The price of each part is rounded up to
        the next 0.01 credit, so every part and `total_cost` have at most 2
        decimal places. In `contact_cost`, each contact type is rounded up on
        its own, and then the types are added. `total_cost` is the sum of the 4
        parts.
      required:
        - agent_cost
        - search_cost
        - enrich_cost
        - contact_cost
        - total_cost
      properties:
        agent_cost:
          type: number
          description: >-
            The agent's work on the search. It grows with the effort of the
            search.
          example: 0.78
        search_cost:
          type: number
          description: >-
            The data that the agent searched. It grows with the effort of the
            search.
          example: 0.14
        enrich_cost:
          type: number
          description: >-
            The records that the agent fetched in full. It grows with the effort
            of the search.
          example: 0
        contact_cost:
          type: number
          description: >-
            The contact data that the agent looked up. Each type is charged once
            for each person who has a value of that type, and a person with no
            value of a type costs 0 for it. It also counts people whose contact
            data the agent looked up and who are not in the final `rows`.
          example: 0
        total_cost:
          type: number
          description: The charge.
          example: 0.92
  responses:
    Unauthorized:
      description: The API key is missing or not valid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            invalid_api_key:
              summary: No API key, or an API key that is not valid
              value:
                error:
                  type: unauthorized
                  message: Invalid API key in request.
                  metadata: []
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key passed as a Bearer token in the `Authorization` header.

````

## Related topics

- [Agent Search API](https://docs.crustdata.com/agent-search-docs/overview.md)
- [API Introduction](https://docs.crustdata.com/openapi-specs/2025-11-01/introduction.md)
- [Web Search API](https://docs.crustdata.com/web-docs/search/introduction.md)
- [Capabilities](https://docs.crustdata.com/general/capabilities.md)
- [Company Search API](https://docs.crustdata.com/company-docs/search/introduction.md)
