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

# Create export

> Creates a new export job for historical data. The export includes data from
your subscription spans that overlap with the requested time range.

Timestamps are in nanoseconds since Unix epoch and can be provided as
integers or strings (for precision with large numbers).




## OpenAPI

````yaml post /v1/exports
openapi: 3.1.0
info:
  title: Ticksupply API
  version: 1.0.0
  description: >
    The Ticksupply API provides programmatic access to cryptocurrency market
    data.

    Subscribe to real-time data streams, manage subscriptions, and export
    historical data.
  contact:
    name: Ticksupply Support
    email: support@ticksupply.com
  termsOfService: https://ticksupply.com/terms
  license:
    name: Proprietary
    url: https://ticksupply.com/terms
servers:
  - url: https://api.ticksupply.com
    description: Production API
security:
  - ApiKeyAuth: []
tags:
  - name: Catalog
    description: Browse available exchanges, instruments, and data streams
  - name: Subscriptions
    description: Manage data stream subscriptions
  - name: Exports
    description: Export historical data to downloadable files
  - name: Availability
    description: Query data availability for specific streams
  - name: Export Schemas
    description: Manage export column schemas for customized CSV output
  - name: Billing
    description: Inspect your plan, access status, and usage for the current billing period
paths:
  /v1/exports:
    post:
      tags:
        - Exports
      summary: Create export
      description: >
        Creates a new export job for historical data. The export includes data
        from

        your subscription spans that overlap with the requested time range.


        Timestamps are in nanoseconds since Unix epoch and can be provided as

        integers or strings (for precision with large numbers).
      operationId: createExport
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateExportRequest'
            examples:
              raw:
                summary: Raw export (default)
                value:
                  datastream_id: 123
                  start_time: 1703116800000000000
                  end_time: 1703203200000000000
              normalized:
                summary: Using a built-in schema
                value:
                  datastream_id: 123
                  start_time: '2024-01-15T10:00:00Z'
                  end_time: '2024-01-16T10:00:00Z'
                  schema: normalized
              inline:
                summary: Inline schema columns
                value:
                  datastream_id: 123
                  start_time: 1703116800000000000
                  end_time: 1703203200000000000
                  schema:
                    columns:
                      - output_column: timestamp_ns
                        meta:
                          value: collection_timestamp_ns
                          format: ns
                      - output_column: price
                        data:
                          binance:
                            json:
                              path: data.p
                              type: decimal(18)
      responses:
        '202':
          description: Export job accepted for processing
          headers:
            Location:
              description: URL of the created export job resource
              schema:
                type: string
                example: /v1/exports/exp_019478a23c5f7b8e9d12abcdef012345
            Retry-After:
              description: Suggested delay in seconds before polling for job status
              schema:
                type: integer
                example: 5
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportJob'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '408':
          $ref: '#/components/responses/RequestTimeout'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      x-codeSamples:
        - lang: python
          label: Python (ticksupply library)
          source: >
            # pip install ticksupply

            from datetime import datetime, timedelta, timezone

            from ticksupply import Client


            client = Client(api_key="<api-key>")

            end = datetime.now(timezone.utc)

            start = end - timedelta(hours=24)

            job = client.exports.create(datastream_id=123, start_time=start,
            end_time=end)

            print(job)
        - lang: rust
          label: Rust (ticksupply crate)
          source: |
            // cargo add ticksupply
            // cargo add tokio --features full
            // cargo add chrono --features clock
            use chrono::{Duration, Utc};
            use ticksupply::Client;

            #[tokio::main]
            async fn main() -> ticksupply::Result<()> {
                let client = Client::with_api_key("<api-key>")?;
                let end = Utc::now();
                let start = end - Duration::hours(24);
                let job = client.exports().create(123, start, end).send().await?;
                println!("{job:#?}");
                Ok(())
            }
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >
        Unique key for idempotent requests. If you retry a request with the same
        key,

        you'll receive the original response without the operation being
        performed again.


        Must be a valid UUID (any version — v4 recommended for uniqueness), up
        to 128 characters.
      schema:
        type: string
        format: uuid
        maxLength: 128
  schemas:
    CreateExportRequest:
      type: object
      required:
        - datastream_id
        - start_time
        - end_time
      properties:
        datastream_id:
          type: integer
          format: int64
          description: Datastream ID to export
        start_time:
          description: >
            Start timestamp. Accepts multiple formats:

            - Nanoseconds since Unix epoch (integer): `1703116800000000000`

            - Nanoseconds since Unix epoch (string): `"1703116800000000000"`

            - ISO 8601 datetime: `"2024-01-15T10:00:00Z"`

            - ISO 8601 with fractional seconds:
            `"2024-01-15T10:00:00.123456789Z"`
          oneOf:
            - type: integer
              format: int64
              example: 1703116800000000000
            - type: string
              example: '2024-01-15T10:00:00Z'
        end_time:
          description: |
            End timestamp. Same formats as start_time.
          oneOf:
            - type: integer
              format: int64
              example: 1703203200000000000
            - type: string
              example: '2024-01-16T10:00:00Z'
        schema:
          description: >
            Export column schema. Controls which columns appear in the output.

            Defaults to `"raw"` (collection_timestamp_ns + raw JSON data blob).


            Accepts:

            - `"raw"` — default two-column output

            - A built-in schema name (e.g., `"normalized"`) — flat columns
            extracted from JSON

            - A schema ID (e.g., `"sch_0194a1b2c3d4e5f6a7b8c9d0e1f2a3b4"`) —
            custom schema by ID

            - An inline object with `columns` array — ad-hoc column definitions


            `"raw"` is a reserved schema name — it is always accepted here but
            is not returned by `GET /v1/export-schemas`.
          default: raw
          oneOf:
            - type: string
              description: Schema name, ID, or "raw"
              example: normalized
            - type: object
              required:
                - columns
              properties:
                columns:
                  type: array
                  items:
                    $ref: '#/components/schemas/CreateSchemaColumnRequest'
                unfold:
                  type: object
                  additionalProperties:
                    $ref: '#/components/schemas/UnfoldConfig'
                  description: Per-exchange unfold rules
                derive:
                  type: object
                  additionalProperties:
                    type: array
                    items:
                      $ref: '#/components/schemas/DeriveField'
                  description: >
                    Per-exchange derived-field rules — same shape as on saved
                    schemas. Useful for ad-hoc exports that need to merge
                    `bids`/`asks` arrays without creating a saved schema.
        format:
          $ref: '#/components/schemas/ExportFormat'
          default: csv
          description: |
            Output file format. Defaults to `csv` for backwards compatibility.
        format_options:
          description: >
            Optional per-format options. Shape must match `format`; mismatched
            or

            unknown keys produce a `400 invalid_argument` response.


            Server defaults are applied when keys are omitted, and the resolved

            options are echoed back on every export response so downstream

            pipelines can pin the exact configuration that was used.
          oneOf:
            - $ref: '#/components/schemas/CsvFormatOptions'
            - $ref: '#/components/schemas/ParquetFormatOptions'
    ExportJob:
      type: object
      required:
        - id
        - datastream_id
        - start_time
        - end_time
        - format
        - format_options
        - status
        - created_at
      properties:
        id:
          type: string
          pattern: ^exp_[a-f0-9]{32}$
          description: Prefixed export job ID (e.g., exp_0194a1b2c3d4e5f6a7b8c9d0e1f2a3b4)
          example: exp_0194a1b2c3d4e5f6a7b8c9d0e1f2a3b4
        datastream_id:
          type: integer
          format: int64
          description: Datastream ID being exported
          example: 123
        start_time:
          type: integer
          format: int64
          description: Start of data range (nanoseconds since Unix epoch)
          example: 1704067200000000000
        end_time:
          type: integer
          format: int64
          description: End of data range (nanoseconds since Unix epoch)
          example: 1704153600000000000
        format:
          $ref: '#/components/schemas/ExportFormat'
        format_options:
          description: >
            Server-resolved per-format options, echoed back with every default
            filled in.

            The shape matches `format`: empty object for `csv`, a populated

            `ParquetFormatOptions` for `parquet`. Pin these values in your
            client to keep

            future server default changes from affecting your pipeline.
          oneOf:
            - $ref: '#/components/schemas/CsvFormatOptions'
            - $ref: '#/components/schemas/ParquetFormatOptions'
        status:
          $ref: '#/components/schemas/ExportStatus'
        reason:
          type: string
          nullable: true
          description: Failure reason (only present when status is "failed")
        created_at:
          type: string
          format: date-time
          description: Creation timestamp
        started_at:
          type: string
          format: date-time
          nullable: true
          description: When processing started
        finished_at:
          type: string
          format: date-time
          nullable: true
          description: When processing finished
    CreateSchemaColumnRequest:
      type: object
      required:
        - output_column
      properties:
        output_column:
          type: string
          description: Column name in the exported file
          example: price
        meta:
          $ref: '#/components/schemas/MetaExtraction'
        data:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ExchangeExtractor'
          description: Per-exchange extraction map (keys are exchange codes)
    UnfoldConfig:
      type: object
      required:
        - path
      properties:
        path:
          type: string
          description: >
            Dot-notation path to a JSON array within the raw message. Each
            element of the array becomes its own row in the output.
          example: data
    DeriveField:
      type: object
      description: >
        A synthetic field computed from the raw message before column
        extraction. Derived fields can be referenced by column paths
        (`data.{field}.{...}`) and targeted by `unfold.path`. The built-in
        `book_update` / `normalized` schema uses this to merge `bids` and `asks`
        into one tagged array.
      required:
        - field
        - op
        - arrays
        - tag_field
        - value_field
      properties:
        field:
          type: string
          description: Name of the synthetic field added to the message before extraction.
          example: changes
        op:
          type: string
          enum:
            - tagged_concat
          description: >-
            Derivation operation. `tagged_concat` concatenates each input array
            and tags its elements with a discriminator.
        arrays:
          type: array
          items:
            type: object
            required:
              - path
              - tag
            properties:
              path:
                type: string
                description: Dot-notation path into the raw message pointing at an array.
                example: data.b
              tag:
                type: string
                description: Tag value applied to each element coming from this array.
                example: bid
        tag_field:
          type: string
          description: Name of the field that receives the tag on each derived element.
          example: side
        value_field:
          type: string
          description: >-
            Name of the field that receives the original array element on each
            derived element.
          example: level
    ExportFormat:
      type: string
      enum:
        - csv
        - parquet
      description: >
        Output container format.


        - `csv` — gzip-compressed CSV with a header row (`.csv.gz`). Type
        information
          is lost; consumers parse strings.
        - `parquet` — columnar Parquet (`.parquet`). Preserves ClickHouse types
          (Decimal, DateTime64(9), Nullable, Array → LIST), supports per-column
          compression, and is read efficiently by pandas, Polars, DuckDB, Athena, and Spark.
    CsvFormatOptions:
      type: object
      additionalProperties: false
      description: >
        Reserved for future CSV-specific options. Currently must be empty or
        omitted —

        any keys are rejected.
    ParquetFormatOptions:
      type: object
      additionalProperties: false
      description: Per-format options applied when `format=parquet`.
      properties:
        compression:
          type: string
          enum:
            - snappy
            - zstd
            - gzip
            - lz4
            - none
          default: zstd
          description: >
            Compression codec applied per column. Server default is `zstd`

            (best ratio, broadly supported by Arrow / pandas / Polars / DuckDB /
            Athena / Spark).

            Pick `snappy` for faster reads, `none` to disable compression
            entirely.
    ExportStatus:
      type: string
      enum:
        - queued
        - running
        - succeeded
        - failed
        - canceled
      description: Export job status
    ApiError:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Error code for programmatic handling
              enum:
                - invalid_argument
                - unauthenticated
                - permission_denied
                - not_found
                - already_exists
                - request_timeout
                - rate_limited
                - payment_required
                - internal
                - unavailable
            message:
              type: string
              description: Human-readable error message
            details:
              type: object
              description: Additional error details (optional)
    MetaExtraction:
      type: object
      required:
        - value
      properties:
        value:
          type: string
          enum:
            - collection_timestamp_ns
          description: System metadata value to extract
        format:
          type: string
          enum:
            - ns
            - us
            - ms
            - s
            - iso8601
          default: ns
          description: Timestamp output format
    ExchangeExtractor:
      type: object
      properties:
        json:
          $ref: '#/components/schemas/JsonExtraction'
        transform:
          type: string
          description: SQL expression with {v} placeholder applied after extraction
    JsonExtraction:
      type: object
      required:
        - path
        - type
      properties:
        path:
          type: string
          description: Dot-notation path into the JSON data (e.g., "p", "data.price")
        type:
          type: string
          description: >
            Data type for extraction. Use decimal(N) for financial values
            (recommended for price/quantity), f64 for percentages, i64 for
            integers, string for text, bool for booleans.
          examples:
            - decimal(18)
            - f64
            - i64
            - string
            - bool
  responses:
    BadRequest:
      description: Invalid request parameters
      headers:
        X-Request-Id:
          description: Unique request identifier for support inquiries
          schema:
            type: string
            example: req_abc123def456
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            error:
              code: invalid_argument
              message: 'Invalid datastream_id: must be a positive integer'
    Unauthorized:
      description: Missing or invalid API key
      headers:
        X-Request-Id:
          description: Unique request identifier for support inquiries
          schema:
            type: string
            example: req_abc123def456
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            error:
              code: unauthenticated
              message: Invalid or missing API key
    PaymentRequired:
      description: >
        Billing-related denial — the plan does not allow this action, or a trial
        cap has been reached.

        Possible triggers include accounts that are suspended for non-payment,
        accounts in a billing

        grace period, and trial accounts that have reached their stream or
        export size limits.
      headers:
        X-Request-Id:
          description: Unique request identifier for support inquiries
          schema:
            type: string
            example: req_abc123def456
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            error:
              code: payment_required
              message: >-
                You have reached the export limit for your trial period. Your
                full plan limits will be available when your trial ends.
    Forbidden:
      description: Permission denied
      headers:
        X-Request-Id:
          description: Unique request identifier for support inquiries
          schema:
            type: string
            example: req_abc123def456
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            error:
              code: permission_denied
              message: No subscription found for this datastream
    RequestTimeout:
      description: |
        Request did not complete within the 10-second deadline. Retry with
        exponential backoff. If you see this consistently on a particular
        endpoint, contact support.
      headers:
        X-Request-Id:
          description: Unique request identifier for support inquiries
          schema:
            type: string
            example: req_abc123def456
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            error:
              code: request_timeout
              message: Request exceeded 10s deadline
    RateLimited:
      description: Rate limit exceeded
      headers:
        X-Request-Id:
          description: Unique request identifier for support inquiries
          schema:
            type: string
            example: req_abc123def456
        Retry-After:
          description: Seconds to wait before retrying
          schema:
            type: integer
        X-RateLimit-Limit-Minute:
          description: Maximum requests allowed per minute
          schema:
            type: integer
        X-RateLimit-Remaining-Minute:
          description: Requests remaining in the current minute window
          schema:
            type: integer
        X-RateLimit-Reset-Minute:
          description: >-
            Unix timestamp (seconds) when the minute window next has capacity.
            Included only when the minute bucket is exhausted.
          schema:
            type: integer
        X-RateLimit-Limit-Hour:
          description: Maximum requests allowed per hour
          schema:
            type: integer
        X-RateLimit-Remaining-Hour:
          description: Requests remaining in the current hour window
          schema:
            type: integer
        X-RateLimit-Reset-Hour:
          description: >-
            Unix timestamp (seconds) when the hour window next has capacity.
            Included only when the hour bucket is exhausted.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            error:
              code: rate_limited
              message: Rate limit exceeded. Retry after 30 seconds.
    InternalError:
      description: Internal server error
      headers:
        X-Request-Id:
          description: Unique request identifier for support inquiries
          schema:
            type: string
            example: req_abc123def456
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            error:
              code: internal
              message: An internal error occurred
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: >-
        Your API key. Get one from the dashboard at
        https://app.ticksupply.com/api-keys

````