# Requests and responses

Every endpoint is one path under /v1, takes the same parameter names and answers in one envelope of 6 parts: code, request_id, data, page, warnings, meta.

## Paths and methods

An endpoint's path is its ID with the dots turned into slashes: `tiktok.videos.search` is `GET /v1/tiktok/videos/search`. A read is a `GET` with its parameters in the query. A request that carries `ids` or `keywords` is a `POST` with a JSON body, so an endpoint that takes one object or a batch accepts both.

```bash
curl -G "https://api.dataxapi.com/v1/tiktok/videos/search" \
  --data-urlencode "query=space station" \
  -H "Authorization: Bearer $DATAXAPI_API_KEY"
```

## Parameters and headers

A name means the same thing on every endpoint, and each endpoint's page lists the ones it takes. A parameter the endpoint does not take is rejected with 400 `invalid_params`; nothing runs and nothing is charged.

- `query`: Search terms
- `id`: ID of the first resource in the path
- `url`: Link to the object, instead of its ID
- `username`: Account handle, instead of its ID
- `ids`: Several IDs in one request
- `keywords`: Several terms in one request
- `sort`: Sort order: `relevance`, `latest`, `popular`; each endpoint lists the ones it takes
- `since`: Published at or after
- `until`: Published at or before
- `published_within`: Published within the last period: `day`, `week`, `month`, `half_year`, `year`; each endpoint lists the ones it takes
- `window`: Statistics period: `24h`, `7d`, `30d`, `90d`; each endpoint lists the ones it takes
- `board`: Which board
- `type`: Content format
- `tab`: Tab as shown on the platform
- `lang`: Language code
- `region`: Country or region code
- `cursor`: Cursor returned by the previous page
- `limit`: Items per page
- `view`: How much of each item to return: `compact`, `standard`, `full`
- `fields`: Return only these fields
- `include`: Extra parts to return alongside

### Request headers

- `Authorization`: `Bearer` and your key: see [Authentication](https://dataxapi.com/docs/authentication/).
- `Idempotency-Key`: Makes a call repeatable without a second charge: see [Billing](https://dataxapi.com/docs/billing/).
- `X-Max-Price`: The most this call may be charged, in US dollars as a decimal string. A call that could cost more is refused before it runs.
- `X-Source`: A label of yours for where the call comes from (a product, a task).
- `X-End-User`: A label of yours for which of your own users the call is for.

The two labels are 1 to 128 visible ASCII characters without spaces. They are only recorded for the usage figures; do not put an email address or a phone number in them.

## The envelope

**Always there**

|  |  |  |
| --- | --- | --- |
| `code` | text | `ok` on a success; on an error, the error's code. |
| `request_id` | text | This call's ID, also in the response header `X-Request-Id`. |

**The data**

|  |  |  |
| --- | --- | --- |
| `data.item` | object | One object, on an endpoint that returns one. |
| `data.items` | list | The objects, on a list or a batch. One of `item` and `items`, never both. |
| `data.missing` | list | A batch only: the inputs that were not found, each with a reason. |

**Paging**

|  |  |  |
| --- | --- | --- |
| `page.next_cursor` | text or null | Pass as `cursor` for the next page; `null` when there is none. |
| `page.cursor_expires_at` | time | Until when that cursor can be used. |
| `page.has_more` | yes/no | Whether there is a next page. |
| `page.returned` | integer | How many items this page holds. |

**About this call**

|  |  |  |
| --- | --- | --- |
| `warnings` | list | What was left out and why, each with a `code`: `items_dropped`, `items_not_requested`, `fields_unparsed`, `text_truncated`. |
| `meta.capability` | text | The endpoint's ID. |
| `meta.result_status` | text | `complete`, `partial` (a batch with inputs not found) or `empty`. |
| `meta.fetched_at` | time | When the data was fetched from the platform. |
| `meta.cached` | yes/no | The data is from a shared snapshot (boards and trends). |
| `meta.replayed` | yes/no | This is the saved result of an earlier call: nothing was added to the bill. |
| `meta.unavailable` | object | The fields this endpoint cannot give, each with the reason. |
| `meta.billing` | object | `amount`, `currency` and `balance_after`. |

An error has a structure of its own, the same on every endpoint: see [Error codes](https://dataxapi.com/docs/errors/).

## When a field has no value

| Case | How it shows |
| --- | --- |
| This item has no such value | The field is `null`. |
| The endpoint cannot give it | The field is absent and listed in `meta.unavailable` with the reason. |
| The view does not hold it | The field is absent; ask for a fuller `view`. |
| It came but could not be read | The field is absent and named in `warnings`. |

## Views and formats

- `compact`: The most used fields; long links (avatars, covers) left out, long text cut to 500 characters and named in `warnings`.
- `standard`: The default: every standard field.
- `full`: Adds the platform's own fields (`ext`) and media addresses that expire.

All three views cost the same.

- Times are ISO 8601 in UTC.
- Amounts of money are decimal strings in US dollars.
- IDs are always strings.
- The fields of each object are on its page, for example [post](https://dataxapi.com/docs/objects/post/); the whole interface is in [openapi.json](https://dataxapi.com/openapi.json).

## Read a result again

A result is kept for 24 hours and can be read again by its request ID at no charge, in any view. The route takes only `view` and `fields`; the answer is that call's envelope with `meta.replayed` true and an `amount` of 0.

```bash
curl -G "https://api.dataxapi.com/v1/calls/{request_id}/result" \
  --data-urlencode "view=full" \
  -H "Authorization: Bearer $DATAXAPI_API_KEY"
```

---

Catalog revision c48ce454ae6c4c65. [HTML version](https://dataxapi.com/docs/requests/)