POST /v1/estimate-dataset

Validates a POST /v1/generate-dataset request and returns its estimated cost and how much of each limit it uses. No data is generated and the request is not charged.

Warning

An estimate is not a guaranteed price. Prices can change. A generation request is charged at the price in effect when it runs, and its response includes the amount charged.

Use it to find errors in a request before sending it, to compare a request against the current limits, and to check that your balance covers the cost.

Request

The body is the same as for POST /v1/generate-dataset: a DatasetRequest. See Building a Request.

curl -X POST https://api.alchemy.example/v1/estimate-dataset \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data @request.json

Requires an API key (see Authentication) but is not billed.

Response

200 with a JSON body when the request passes every check:

Property	Type	Description
`estimatedCost`	`number`	The estimated cost of the request at the time of the estimate, in `currency`.
`currency`	`string`	ISO 4217 code of the currency of `estimatedCost` and `balance`.
`balance`	`number`	Your balance at the time of the estimate.
`balanceCovers`	`boolean`	Whether `balance` covers `estimatedCost`.
`limits`	`object`	How much of each limit the request uses. See below.

limits has one entry for each limit on a request. See How large a request can be. Each entry has requested, the amount the request uses, and limit, the current maximum for one request:

Entry	Counts
`rows`	Rows across every table.
`columns`	Columns in the table with the most columns.
`dataBytes`	The estimated size of the generated data, in bytes.
`calculationSteps`	`Calculated` steps across every table.

For a request with one 500-row table of three columns, limits has this structure:

{
  "rows": { "requested": 500, "limit": 100000 },
  "columns": { "requested": 3, "limit": 25 },
  "dataBytes": { "requested": 48000, "limit": 268435456 },
  "calculationSteps": { "requested": 0, "limit": 50000000 }
}

The limit values change over time. The values above are an example. Use the values in the response.

dataBytes is an estimate based on each field's settings, so the generated data is usually smaller.

What is checked

The request is checked in the same way as a generation request before any data is generated:

the structure of the body, the field types, and every field's settings
table names, column names, mapped sub-fields and data types
the limits on a request
references to other tables, and the data types of the columns they copy
unique, against the number of distinct values each field's settings allow
a field that writes a primaryKey column and sets a null percentage above 0
the columns each Calculated field reads

A request that fails a check returns the same error a generation request returns. See Errors.

Some checks require the generated data, so an estimate cannot make them. A request that passes the estimate can still be rejected when it is generated, for these reasons:

a unique Reference field, or one with rule Unique, needs more distinct values than the referenced table contains
a unique field produces fewer distinct values than its settings allow, because some values repeat
a column listed in primaryKey contains a repeated value or an empty value
the generated data is larger than its estimate and exceeds the data limit

An estimate does not reserve anything. Your balance can change between the estimate and the generation request.

Errors

All error responses are RFC 7807 ProblemDetails bodies, the same as the generation endpoints. See POST /v1/generate-dataset for each one. An estimate never returns 402, because nothing is charged. balanceCovers reports whether the balance covers the cost instead.

400, because a field's settings allow fewer distinct values than its unique rows need:

{
  "type": "urn:alchemy:error:invalid-generation-request",
  "title": "Invalid generation request.",
  "status": 400,
  "detail": "This field (table 'customer', column 'customer_id') is unique for 500 rows, but its settings allow only 10 distinct value(s). Lower rowCount, widen the field's range, or turn off unique.",
  "path": "$.tables[0].fields[0]",
  "table": "customer",
  "fieldIndex": 0,
  "fieldType": "Number",
  "columns": ["customer_id"]
}