> ## 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 export cost

> Compare export choices and forecast the cost before starting a download job.

## Credits and plans

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

| Usage | PAYG | AYCE |
| - | - | - |
| Estimate request | **Free**<br />0 credits | **Included**<br />0 credits |

Estimate creates no credit hold or export job.

Use Estimate to forecast the cost of a contact export after you have
counted the audience and checked a free sample. Send the same filter,
row cap, columns, and `reveal` choices you plan to send to Export.

## Choose what to retrieve

Set `maxRows` to the number of contacts you want. Use `reveal` to
choose which contact details you retrieve; `columns` controls which fields
appear in the file.

| Export `reveal` | PAYG: credits per row | AYCE |
| - | - | - |
| `[]` | 1 for the contact profile | **Unlimited**<br />0 credits |
| `["email"]` | 1 for the row, +1 for a populated email | **Unlimited**<br />0 credits |
| `["mobile"]` | 1 for the row, +10 for a populated mobile | **Unlimited**<br />0 credits |
| `["email", "mobile"]` | 1 for the row, +1 for a populated email, +10 for a populated mobile | **Unlimited**<br />0 credits |

* PAYG exports add **10 credits per SmartSearch filter node**, once per request. This means each semantic or lookalike node; ordinary field conditions add no search fee.
* SmartSearch adds **0 credits on AYCE** and is free on Count and View on both plans.
* Per-request and [rate limits](/api-reference/v2/rate-limits) apply to both plans, including unlimited AYCE retrieval.

<Warning>
  Omitting `reveal`, or sending `null`, selects **both email and mobile**.
  Removing those fields from `columns` does not remove their reveal charges.
  Set `reveal` explicitly to control the cost.
</Warning>

## Example: estimate 100 contacts with email

Set your API key as `REVENUEBASE_API_KEY`. This reuses the Count/View
audience, caps the export at 100 rows, and excludes mobile charges.

```bash
curl --request POST 'https://api.revenuebase.ai/v2/contact/exports/estimate' \
  --header "X-Key: $REVENUEBASE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "filter": {
      "type": "group",
      "op": "AND",
      "children": [
        {
          "type": "condition",
          "column": "COUNTRY_NAME_PER",
          "operator": "eq",
          "value": "United States"
        },
        {
          "type": "condition",
          "column": "JOB_LEVEL_PER",
          "operator": "eq",
          "value": "VP"
        }
      ]
    },
    "columns": [
      "FULL_NAME_PER",
      "JOB_TITLE_PER",
      "COMPANY_NAME_ORG",
      "EMAIL_ADDRESS_PER"
    ],
    "maxRows": 100,
    "reveal": [
      "email"
    ],
    "format": "csv",
    "compression": "gz"
  }'
```

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

```json
{
  "creditsEstimate": 200
}
```

**AYCE response for the same request:**

```json
{ "creditsEstimate": null }
```

| Field | What it means |
| - | - |
| `creditsEstimate` as a number | Forecast credits for this request's filter, row cap, and reveal choices. |
| `creditsEstimate: null` | Export credit metering is not applied to this account or the current service configuration, including AYCE accounts. It is not an estimate error. |

## Estimate, hold, and final charge

These are three different amounts:

| Amount | Meaning |
| - | - |
| Estimate | A forecast based on audience counts and contact-detail availability. Counts and data can change; this is not a guaranteed ceiling. |
| Hold | Credits reserved when Export starts. With `maxRows`, it assumes every requested row has every selected contact detail. |
| Final charge | The rows actually written, populated selected details, and paid SmartSearch filter nodes. Unused held credits are released. |

For the example above, `maxRows: 100` and `reveal: ["email"]` require
a hold of up to **200 credits**. If the file contains 100 contacts
but only 80 have an email, the final charge is **180 credits**.

With both details selected, 100 contacts and one SmartSearch node
require a hold of up to **1,210 credits**. If 80 have email and 20
have mobile, the final charge is **390 credits**:
`100 + 80 + (20 × 10) + 10`.

<Note>
  Your balance must cover the hold, even when the expected final charge
  is smaller. Export returns `402 INSUFFICIENT_CREDITS` if it cannot
  reserve that amount; it does not automatically export a smaller subset.
</Note>

## Keep the request within a budget

Read your balance with `GET /v2/account/balance`. Current unit prices
are available from the free `GET /v2/contact/credits/prices` endpoint.

For an upper bound, allow 1, 2, 11, or 12 credits per contact row
according to the `reveal` table, plus 10 per SmartSearch node. With
200 credits and no SmartSearch nodes, an email-only export can cap at
100 rows. Using both details would cap at 16 rows. Always send a
positive `maxRows`; `0` does not mean a zero-row export.

## Errors and next step

A `503 ESTIMATE_UNAVAILABLE` means the count used for the forecast
timed out. Do not interpret it as a zero-credit export. You can retry
after `Retry-After`, narrow the filter, or decide to proceed with an
explicit affordable `maxRows` and `reveal` upper bound.

A `422` means the request or filter needs correction. Estimate does
not validate every file-format, filename, or requested-column choice;
choose fields from the column catalog before starting the export.
On a `429`, wait
for the rate-limit reset. No estimate response starts a paid job.

When the choices and budget are right, send the **same body** to
[Export](/api-reference/start-export). Changing the filter, row cap,
or reveal choices requires a new estimate.


## OpenAPI

````yaml /api-reference/v2/contact-openapi.json post /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:
  /exports/estimate:
    post:
      summary: Estimate Export
      description: >-
        Forecast a contact export's credits without reserving credits or
        creating a job. Send the same filter, columns, maxRows, and reveal
        choices you plan to export. creditsEstimate is a forecast, not a hard
        budget ceiling; the start can require a larger upper-bound hold. A null
        estimate means export credit metering is not applied to the account or
        current service configuration, rather than a failed estimate.
      operationId: estimate_export_v1_exports_estimate_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExportRequest'
            example:
              filter:
                type: group
                op: AND
                children:
                  - type: condition
                    column: COUNTRY_NAME_PER
                    operator: eq
                    value: United States
                  - type: condition
                    column: JOB_LEVEL_PER
                    operator: eq
                    value: VP
              columns:
                - FULL_NAME_PER
                - JOB_TITLE_PER
                - COMPANY_NAME_ORG
                - EMAIL_ADDRESS_PER
              maxRows: 100
              reveal:
                - email
              format: csv
              compression: gz
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Estimate Export V1 Exports Estimate Post
              example:
                creditsEstimate: 200
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    ExportRequest:
      properties:
        filter:
          anyOf:
            - $ref: '#/components/schemas/GroupNode'
            - type: 'null'
          description: >-
            Audience filter, shared with Count and View. Omitted/null selects
            the entire dataset. Each semantic/lookalike node adds 10 credits on
            a paid export.
        columns:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Columns
          description: >-
            Fields written to the file. Omitted/null uses the default set; ["*"]
            requests all. Removing email/mobile columns does not remove reveal
            charges.
        format:
          type: string
          title: Format
          default: json
          description: >-
            File format: csv, json (default), or parquet. Does not change unit
            credit prices.
        compression:
          type: string
          title: Compression
          default: gz
          description: gz (default), zip, or none. Does not change unit credit prices.
        maxRows:
          anyOf:
            - type: integer
            - type: 'null'
          title: Maxrows
          description: >-
            Positive row cap, up to 1,000,000. With an explicit cap, the hold
            assumes every selected contact detail is populated on every capped
            row. Omitted/null or 0 uses the maximum; 0 does not mean zero rows.
          x-mint:
            post:
              - Caps rows and credit hold
        filename:
          anyOf:
            - type: string
            - type: 'null'
          title: Filename
          description: >-
            Optional base filename: 1–150 letters, digits, spaces, or . _ ( ) -.
            The API adds the selected file/compression extension.
        reveal:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Reveal
          description: >-
            Buy email (+1 per populated value), mobile (+10), both, or neither
            ([]), in addition to 1 per contact row. Omitted/null buys both.
            Columns do not change these charges. Unselected requested fields
            become availability booleans.
          x-mint:
            post:
              - Changes credit cost
      type: object
      title: ExportRequest
    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.