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

# Estimate Company Export

> Forecast the credit cost of a company file before starting its export job.

## Credits and plans

PAYG is Pay-as-you-go. AYCE is All-you-can-eat.

| Usage | PAYG | AYCE |
| - | - | - |
| Estimate; no job or hold | **Free** 0 credits | **Free** 0 credits |

## When to use Company Estimate

Check a proposed company file before reserving credits. Send the same filter, columns, format, compression, and maxRows you intend to use for [Company Export](https://docs.revenuebase.ai/api-reference/start-company-export.md).

## Example

Set `REVENUEBASE_API_KEY` to your API key.

```bash
curl --request POST 'https://api.revenuebase.ai/v2/contact/company/exports/estimate' \
  --header "X-Key: $REVENUEBASE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "filter": {
      "type": "group",
      "op": "AND",
      "children": [
        {
          "type": "condition",
          "column": "HEADQUARTERS_COUNTRY_NAME_ORG",
          "operator": "eq",
          "value": "United States"
        }
      ]
    },
    "columns": [
      "RBID_ORG",
      "COMPANY_NAME_ORG",
      "DOMAIN_ORG"
    ],
    "format": "csv",
    "compression": "none",
    "maxRows": 100,
    "filename": "us-companies"
  }'
```

Response captured from the local test API on October 13, 2026. Results can change as the dataset or account changes.

```json
{
  "creditsEstimate": 100
}
```

## Read the forecast

`creditsEstimate` is the amount the service would reserve for this PAYG request. It is `null` when export metering does not apply, including AYCE. The call creates no export job and reserves no credits.

The PAYG chart is **1 credit per company row, plus 10 per SmartSearch filter node per request**. Selected company fields do not add contact email/mobile reveal charges.

## Estimate, hold, and charge

Estimate and Start use the same calculation. They count matching companies up to `maxRows` at one credit per company and add 10 credits per SmartSearch node. If 60 companies match and `maxRows` is 100, the reserve is **60 credits** before any SmartSearch fees. A fresh calculation may change if the underlying data or request changes. The final charge uses the companies written plus any SmartSearch node fees.

Set a positive integer for `maxRows` to cap the job. Omit it or send `null` to use the service maximum of 1,000,000 rows. Sending `0` returns `422 INVALID_REQUEST`. Company and person/job criteria are supported for company files.

## Errors and retries

Correct unsupported fields or filters before retrying a 400 or 422 response. If a 429 response is returned, wait for Retry-After. Contact and company routes share the [default 10 requests per second per user](https://docs.revenuebase.ai/api-reference/v2/rate-limits.md).

## Next steps

Review the budget, then call [Start Company Export](https://docs.revenuebase.ai/api-reference/start-company-export.md) with the same body. Reduce maxRows if the hold is too large.


## OpenAPI

````yaml /api-reference/v2/contact-openapi.json post /company/exports/estimate
openapi: 3.1.0
info:
  title: RevenueBase Velocity API
  version: 0.1.0
servers:
  - url: https://api.revenuebase.ai/v2/contact
    description: Production
security: []
paths:
  /company/exports/estimate:
    post:
      summary: Estimate Company Export
      description: >-
        What POST /v1/company/exports would hold for this body, without holding

        anything. `creditsEstimate: null` = this account isn't metered for
        exports

        (AYCE, no attributable user, or exports metering off).
      operationId: estimate_company_export_v1_company_exports_estimate_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyExportDocumentationRequest'
            example:
              filter:
                type: group
                op: AND
                children:
                  - type: condition
                    column: HEADQUARTERS_COUNTRY_NAME_ORG
                    operator: eq
                    value: United States
              columns:
                - RBID_ORG
                - COMPANY_NAME_ORG
                - DOMAIN_ORG
              format: csv
              compression: none
              maxRows: 100
              filename: us-companies
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: >-
                  Response Estimate Company Export V1 Company Exports Estimate
                  Post
              example:
                creditsEstimate: 100
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    CompanyExportDocumentationRequest:
      properties:
        filter:
          anyOf:
            - $ref: '#/components/schemas/GroupNode'
            - type: 'null'
          description: Company or contact conditions selecting distinct companies.
        columns:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Columns
          description: >-
            Company fields to write; omitted or empty uses company defaults.
            ["*"] expands to company catalog fields.
        format:
          type: string
          title: Format
          default: json
          description: 'File format: csv, json, or parquet; json by default.'
        compression:
          type: string
          title: Compression
          default: gz
          description: 'File compression: gz, zip, or none; gz by default.'
        maxRows:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Maxrows
          description: >-
            Positive integer row cap. Omit or send null to use the service
            maximum of 1,000,000. Sending 0 returns 422 INVALID_REQUEST.
        filename:
          anyOf:
            - type: string
            - type: 'null'
          title: Filename
          description: >-
            Optional base filename, up to 150 characters. The service adds the
            format and compression extension.
        reveal:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Reveal
          description: >-
            Ignored for company files. Company fields do not add contact email
            or mobile reveal charges.
      type: object
      title: CompanyExportDocumentationRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    GroupNode:
      properties:
        type:
          type: string
          const: group
          title: Type
        op:
          type: string
          enum:
            - AND
            - OR
          title: Op
          default: AND
        children:
          items:
            oneOf:
              - $ref: '#/components/schemas/ConditionNode'
              - $ref: '#/components/schemas/GroupNode'
              - $ref: '#/components/schemas/SemanticNode'
              - $ref: '#/components/schemas/LookalikeNode'
            discriminator:
              propertyName: type
              mapping:
                condition: '#/components/schemas/ConditionNode'
                group: '#/components/schemas/GroupNode'
                lookalike: '#/components/schemas/LookalikeNode'
                semantic: '#/components/schemas/SemanticNode'
          type: array
          title: Children
        joinWithPrevious:
          anyOf:
            - type: string
              enum:
                - AND
                - OR
            - type: 'null'
          title: Joinwithprevious
        negate:
          type: boolean
          title: Negate
          default: false
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
      type: object
      required:
        - type
      title: GroupNode
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    ConditionNode:
      properties:
        type:
          type: string
          const: condition
          title: Type
        column:
          type: string
          title: Column
          default: ''
        operator:
          type: string
          enum:
            - eq
            - ne
            - gt
            - gte
            - lt
            - lte
            - contains
            - startsWith
            - endsWith
            - isNull
            - isNotNull
            - in
            - notIn
            - between
          title: Operator
        value:
          anyOf:
            - type: string
            - type: integer
            - type: number
            - type: boolean
            - type: 'null'
          title: Value
        value2:
          anyOf:
            - type: string
            - type: integer
            - type: number
            - type: boolean
            - type: 'null'
          title: Value2
        valueList:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Valuelist
        joinWithPrevious:
          anyOf:
            - type: string
              enum:
                - AND
                - OR
            - type: 'null'
          title: Joinwithprevious
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
      type: object
      required:
        - type
        - operator
      title: ConditionNode
    SemanticNode:
      properties:
        type:
          type: string
          const: semantic
          title: Type
        'on':
          type: string
          enum:
            - company
            - title
          title: 'On'
        text:
          type: string
          title: Text
          default: ''
        maxDistance:
          anyOf:
            - type: number
            - type: 'null'
          title: Maxdistance
        match:
          anyOf:
            - type: string
              enum:
                - exact
                - similar
                - related
                - broad
                - same
            - type: 'null'
          title: Match
        joinWithPrevious:
          anyOf:
            - type: string
              enum:
                - AND
                - OR
            - type: 'null'
          title: Joinwithprevious
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
        negate:
          type: boolean
          title: Negate
          default: false
      type: object
      required:
        - type
        - 'on'
      title: SemanticNode
    LookalikeNode:
      properties:
        type:
          type: string
          const: lookalike
          title: Type
        rbidOrg:
          type: string
          title: Rbidorg
          default: ''
        domain:
          type: string
          title: Domain
          default: ''
        maxDistance:
          anyOf:
            - type: number
            - type: 'null'
          title: Maxdistance
        match:
          anyOf:
            - type: string
              enum:
                - exact
                - similar
                - related
                - broad
                - same
            - type: 'null'
          title: Match
        joinWithPrevious:
          anyOf:
            - type: string
              enum:
                - AND
                - OR
            - type: 'null'
          title: Joinwithprevious
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
        negate:
          type: boolean
          title: Negate
          default: false
      type: object
      required:
        - type
      title: LookalikeNode
      description: |-
        Match people at companies whose NAME-FREE description vector is near the
        given company's vector (velocity.company_vec512_lookalike).
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-Key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.