openapi: 3.0.3
info:
  contact:
    email: support@marqeta.com
    name: Marqeta
  description: Marqeta's Core API endpoints, conveniently annotated to enable code generation (including SDKs), test cases, and documentation. Currently in beta.
  termsOfService: https://www.marqeta.com/api-terms
  title: Core accepted countries Loads API
  version: 3.0.39
servers:
- url: /v3
security:
- mqAppAndAccessToken: []
tags:
- name: Loads
  description: Retrieve funding load transaction data at a specified aggregation level. Covers all load types including ACH, push-to-card, and program transfers.
paths:
  /views/loads/{time_agg}:
    get:
      operationId: getLoads
      summary: Retrieve funding load data
      description: Returns funding load transaction data at a specified aggregation level. When using the detail aggregation level, each row represents a single funding load transaction. Supports daily, weekly, monthly, and detail levels. Covers ACH loads, push-to-card loads, and program transfers.
      tags:
      - Loads
      parameters:
      - $ref: '#/components/parameters/time_agg'
      - $ref: '#/components/parameters/program'
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/start_date'
      - $ref: '#/components/parameters/end_date'
      - $ref: '#/components/parameters/format'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Load transaction data for the specified time period.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoadsResponse'
            text/csv:
              schema:
                type: string
                description: CSV-formatted load data.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  parameters:
    offset:
      name: offset
      in: query
      description: Zero-based offset for pagination.
      schema:
        type: integer
        minimum: 0
        default: 0
    fields:
      name: fields
      in: query
      description: Comma-delimited list of fields to include in the response. If not specified, all available fields are returned.
      schema:
        type: string
    format:
      name: format
      in: query
      description: Response format. Use 'json' for JSON responses or 'csv' for comma-separated bulk file format. Defaults to json.
      schema:
        type: string
        enum:
        - json
        - csv
        default: json
    time_agg:
      name: time_agg
      in: path
      required: true
      description: Aggregation time level for the data. Use 'day' for daily rollups, 'week' for weekly rollups, 'month' for monthly rollups, or 'detail' for individual record-level data.
      schema:
        type: string
        enum:
        - day
        - week
        - month
        - detail
    end_date:
      name: end_date
      in: query
      description: End date for filtering data (format YYYY-MM-DD). Returns records on or before this date.
      schema:
        type: string
        format: date
    start_date:
      name: start_date
      in: query
      description: Start date for filtering data (format YYYY-MM-DD). Returns records on or after this date.
      schema:
        type: string
        format: date
    limit:
      name: limit
      in: query
      description: Maximum number of records to return per request.
      schema:
        type: integer
        minimum: 1
        maximum: 10000
        default: 1000
    program:
      name: program
      in: query
      required: true
      description: The name of your Marqeta card program. This parameter is required for most DiVA API endpoints to scope the data to your program.
      schema:
        type: string
  responses:
    Unauthorized:
      description: Unauthorized. The provided application token and access token credentials are invalid or missing.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request. One or more required query parameters are missing or contain invalid values.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    DivaResponseMeta:
      type: object
      description: Metadata included in DiVA API paginated responses.
      properties:
        total_count:
          type: integer
          description: Total number of records matching the query.
        limit:
          type: integer
          description: Maximum records returned per page.
        offset:
          type: integer
          description: Current page offset.
        has_more:
          type: boolean
          description: Whether additional pages of data are available.
    ErrorResponse:
      type: object
      description: Standard error response returned by the Marqeta DiVA API.
      properties:
        error_code:
          type: string
          description: Machine-readable error code.
        error_message:
          type: string
          description: Human-readable error description.
    LoadsResponse:
      type: object
      description: Funding load transaction data response.
      properties:
        meta:
          $ref: '#/components/schemas/DivaResponseMeta'
        data:
          type: array
          description: Array of load transaction records.
          items:
            type: object
            properties:
              date:
                type: string
                description: Load date or aggregation period.
              program:
                type: string
                description: Program identifier.
              load_count:
                type: integer
                description: Number of load transactions in the period.
              total_load_amount:
                type: number
                description: Total amount loaded during the period.
              load_type:
                type: string
                description: Type of funding load (ACH, push-to-card, transfer).
              currency_code:
                type: string
                description: ISO 4217 currency code.
  securitySchemes:
    mqAppAndAccessToken:
      scheme: basic
      type: http