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

# Exports API

Retrieve all attributed events for your app within a given time window. Supports multiple output formats for data pipeline and analytics integrations.

## Authentication

Every request must include an `Authorization` header containing your Appstack API key. You can find your API key in the Appstack dashboard under your app settings.

```text theme={null}
Authorization: <your-api-key>
```

<Note>
  API keys are scoped to a single app. The response will only include events for the app associated with the key.
</Note>

## Endpoint

```text theme={null}
GET https://api.appstack.tech/api/v1/export
```

## Request

### Query Parameters

<ParamField query="timestamp" type="integer" required>
  Unix timestamp (seconds) defining the start of the export window. Returns all events from this timestamp up to the current time.

  Example: `1700000000`
</ParamField>

<ParamField query="format" default="json" type="string">
  Output format for the response. Accepted values:

  | Value     | Description                                         |
  | --------- | --------------------------------------------------- |
  | `json`    | Structured JSON object (default)                    |
  | `ndjson`  | Newline-delimited JSON — one event per line         |
  | `csv`     | Comma-separated values, returned as a file download |
  | `tsv`     | Tab-separated values, returned as a file download   |
  | `xml`     | XML document, returned as a file download           |
  | `xlsx`    | Excel workbook (.xlsx), returned as a file download |
  | `parquet` | Apache Parquet binary, returned as a file download  |
</ParamField>

<ParamField query="limit" type="integer" default="10000">
  Maximum number of events to return in a single response. Must be between `1`
  and `10000` (the maximum page size). Use together with `offset` to page through
  large result sets.
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Number of events to skip before returning results. Page through the full window
  by incrementing `offset` in steps of `limit`.
</ParamField>

<Note>
  Results are ordered by `event_time` (ascending). A response is the last page
  when it contains fewer than `limit` events — keep requesting with an increasing
  `offset` until then.
</Note>

### Example request

```bash theme={null}
curl -X GET "https://api.appstack.tech/api/v1/export?timestamp=1700000000&format=json" \
  -H "Authorization: <your-api-key>"
```

## Response

For `format=json`, the endpoint returns a JSON object. For all other formats, the response is streamed as a file download with the appropriate `Content-Disposition` header.

### JSON response

```json theme={null}
{
  "data": [
    {
      "event_id": "abc123",
      "event_time": "2024-11-14T12:00:00Z",
      "event_name": "appstack_purchase",
      "appstack_id": "as_xyz789",
      "media_source": "meta",
      "campaign_id": "12345678",
      "campaign_name": "iOS - Broad - US",
      "adset_id": "98765432",
      "adset_name": "Interest - Football",
      "ad_id": "11223344",
      "ad_name": "Video - 15s",
      "matching_type": "network",
      "click_to_first_open_hours": 1,
      "confidence_score": "high",
      "country": "US",
      "os": "ios",
      "app_id": "6741685163",
      "app_name": "My app name",
      "install_type": "new_install",
      "revenue": 9.99,
      "currency": "USD",
      "idfv": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890",
      "maid": "38400000-8cf0-11bd-b23e-10b96e40000d",
      "customer_user_id": "user_42",
      "revenue_usd": 9.99
    }
  ],
  "total_count": 1
}
```

### Response fields

<ResponseField name="data" type="array">
  Array of attributed events.

  <Expandable title="Event object">
    <ResponseField name="event_id" type="string | null">
      Unique identifier for the event.
    </ResponseField>

    <ResponseField name="event_time" type="string | null">
      ISO 8601 timestamp of when the event occurred.
    </ResponseField>

    <ResponseField name="event_name" type="string | null">
      Prefixed event name in the format `appstack_<event>`. For example: `appstack_purchase`, `appstack_level_complete`.
    </ResponseField>

    <ResponseField name="appstack_id" type="string | null">
      Appstack's unique installation identifier for the device.
    </ResponseField>

    <ResponseField name="media_source" type="string | null">
      The ad network or source attributed to this event. Examples: `meta`, `google`, `tiktok`, `organic`.
    </ResponseField>

    <ResponseField name="campaign_id" type="string | null">
      ID of the attributed campaign.
    </ResponseField>

    <ResponseField name="campaign_name" type="string | null">
      Name of the attributed campaign.
    </ResponseField>

    <ResponseField name="adset_id" type="string | null">
      ID of the attributed ad set.
    </ResponseField>

    <ResponseField name="adset_name" type="string | null">
      Name of the attributed ad set.
    </ResponseField>

    <ResponseField name="ad_id" type="string | null">
      ID of the attributed ad.
    </ResponseField>

    <ResponseField name="ad_name" type="string | null">
      Name of the attributed ad.
    </ResponseField>

    <ResponseField name="matching_type" type="string | null">
      The attribution method used. Possible values: `network`, `geo`.
    </ResponseField>

    <ResponseField name="click_to_first_open_hours" type="integer | null">
      Number of hours between the attributed click and the user's first app open.
    </ResponseField>

    <ResponseField name="confidence_score" type="string | null">
      Confidence level of the attribution match. Possible values: `low`, `medium`, `high`.
    </ResponseField>

    <ResponseField name="country" type="string | null">
      ISO 3166-1 alpha-2 country code of the user at the time of the event.
    </ResponseField>

    <ResponseField name="os" type="string | null">
      Operating system. Possible values: `ios`, `android`.
    </ResponseField>

    <ResponseField name="app_id" type="string | null">
      Bundle ID or package name of the app (e.g. `com.example.app`).
    </ResponseField>

    <ResponseField name="app_name" type="string | null">
      Human-readable name of the app.
    </ResponseField>

    <ResponseField name="install_type" type="string | null">
      iOS only. Indicates whether this was a fresh install or a reinstall. Possible values: `new_install`, `reinstall_same_device`.
    </ResponseField>

    <ResponseField name="revenue" type="number | null">
      Decrypted revenue amount associated with the event.
    </ResponseField>

    <ResponseField name="currency" type="string | null">
      ISO 4217 currency code for the revenue field (e.g. `USD`, `EUR`).
    </ResponseField>

    <ResponseField name="idfv" type="string | null">
      iOS Identifier for Vendor. Present on iOS events when available. Used by Amplitude and similar SDKs as `device_id` to merge server-side events with in-app SDK events for the same device.
    </ResponseField>

    <ResponseField name="maid" type="string | null">
      Mobile Advertising ID — GAID on Android, IDFA on iOS when consented. Present when available. Used by Amplitude and similar SDKs as `device_id` on Android to merge server-side events with in-app SDK events.
    </ResponseField>

    <ResponseField name="customer_user_id" type="string | null">
      Your own user identifier, as set through the Appstack SDK. `null` when the app never identified the user.
    </ResponseField>

    <ResponseField name="revenue_usd" type="number | null">
      Revenue converted to USD using the exchange rate of the event date. `null` for non-revenue events.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total_count" type="integer">
  Number of events returned in this response (i.e. in the current page).
</ResponseField>

## Errors

| Status | Code                  | Description                                                                                 |
| ------ | --------------------- | ------------------------------------------------------------------------------------------- |
| `401`  | Unauthorized          | Missing or invalid `Authorization` header.                                                  |
| `422`  | Unprocessable Entity  | `timestamp` is missing, `format` is not a valid value, or `limit`/`offset` is out of range. |
| `500`  | Internal Server Error | Unexpected error while fetching or building the export.                                     |

### Error response shape

```json theme={null}
{
  "error": "Unauthorized",
  "detail": "Authorization header is required"
}
```