Algo Trader Tools Copy events API

openapi: 3.2.0
info:
  title: Algo Trader Tools Copy events API
  version: 1.0.0
  description: 'Connect MetaTrader 4 and 5 accounts, set up trade copiers and attach followers with their own rules, from your own code.


    * Authenticate with `Authorization: Bearer att_…` (or `X-API-Key`). Create keys in the app under **API keys**.

    * Errors are RFC 9457 problem details (`application/problem+json`) with a stable `code`.

    * Lists are cursor-paginated: `limit` (1 to 100) and `cursor`; read `has_more` and `next_cursor`.

    * Rate limits: 120 requests a minute per key, and 5 account connects, reconnects and disconnects a minute per user. Headers: `RateLimit-Policy`, `RateLimit`, and `Retry-After` on 429.'
  contact:
    name: Algo Trader Tools
    url: https://algotradertools.com
servers:
- url: https://api.algotradertools.com
  description: Production
security:
- ApiKey: []
- ApiKeyHeader: []
tags:
- name: Copy events
  description: What the copier engine did on each follower, kept for 90 days.
paths:
  /v1/copiers/{copier_id}/events:
    parameters:
    - $ref: '#/components/parameters/CopierId'
    get:
      operationId: list_copy_events
      tags:
      - Copy events
      summary: List copy events
      description: 'What the copier engine did, or decided not to do, on the copier''s followers, newest first. Events are kept for 90 days.


        Scope: `copiers:read`.'
      responses:
        '200':
          description: A page of events.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CopyEventList'
              example:
                object: list
                data:
                - id: 48213
                  object: copy_event
                  follower_id: 9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d
                  account_id: 0b7e5c1a-2f3d-4e6a-8b9c-7d6e5f4a3b2c
                  master_ticket: 771203398
                  action: open
                  ok: true
                  message: Opened 0.20 lots XAUUSD
                  detail:
                    symbol: XAUUSD
                    side: buy
                    volume: 0.2
                    ticket: 99120443
                  received_at: '2026-10-25T14:03:51.204Z'
                  engine_ms: 0.42
                  execution_ms: 182.6
                  total_ms: 183.02
                has_more: false
                next_cursor: null
        '400':
          description: '- `invalid_cursor`: The cursor wasn''t one this API returned.

            - `validation_failed`: A field is missing or invalid; see errors.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://algotradertools.com/docs/errors#invalid_cursor
                title: Invalid cursor
                status: 400
                code: invalid_cursor
                detail: The cursor wasn't one this API returned.
                request_id: b7c1e2d4-5f6a-4b8c-9d0e-1f2a3b4c5d6e
                doc_url: https://algotradertools.com/docs/errors#invalid_cursor
        '401':
          description: '- `authentication_required`: No API key was sent.

            - `invalid_api_key`: The API key is unknown or malformed.

            - `api_key_revoked`: The API key was revoked.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://algotradertools.com/docs/errors#authentication_required
                title: Authentication required
                status: 401
                code: authentication_required
                detail: No API key was sent.
                request_id: b7c1e2d4-5f6a-4b8c-9d0e-1f2a3b4c5d6e
                doc_url: https://algotradertools.com/docs/errors#authentication_required
        '403':
          description: '- `insufficient_scope`: The API key lacks the scope this endpoint needs.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://algotradertools.com/docs/errors#insufficient_scope
                title: Insufficient scope
                status: 403
                code: insufficient_scope
                detail: This API key doesn't have the copiers:read scope. Create a key that has it.
                request_id: b7c1e2d4-5f6a-4b8c-9d0e-1f2a3b4c5d6e
                doc_url: https://algotradertools.com/docs/errors#insufficient_scope
        '404':
          description: '- `not_found`: No such resource or endpoint.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://algotradertools.com/docs/errors#not_found
                title: Not found
                status: 404
                code: not_found
                detail: No such resource or endpoint.
                request_id: b7c1e2d4-5f6a-4b8c-9d0e-1f2a3b4c5d6e
                doc_url: https://algotradertools.com/docs/errors#not_found
        '429':
          description: '- `rate_limited`: Wait for the number of seconds in Retry-After.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://algotradertools.com/docs/errors#rate_limited
                title: Too many requests
                status: 429
                code: rate_limited
                detail: Request was throttled. Expected available in 21 seconds.
                request_id: b7c1e2d4-5f6a-4b8c-9d0e-1f2a3b4c5d6e
                doc_url: https://algotradertools.com/docs/errors#rate_limited
      parameters:
      - $ref: '#/components/parameters/FollowerIdFilter'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Cursor'
components:
  schemas:
    CopyEvent:
      type: object
      properties:
        id:
          type: integer
          example: 48213
        object:
          type: string
          enum:
          - copy_event
          description: What this object is.
        follower_id:
          type: string
          description: The follower it happened on.
          format: uuid
          example: 9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d
        account_id:
          type: string
          description: That follower's account.
          format: uuid
          example: 0b7e5c1a-2f3d-4e6a-8b9c-7d6e5f4a3b2c
        master_ticket:
          type: integer
          description: The master position it's about.
          example: 771203398
        action:
          type: string
          enum:
          - open
          - close
          - partial_close
          - modify
          - skip
          - adopt
          - place
          - cancel
          description: '`open`, `close`, `partial_close`, `modify` (stop loss or take profit, or a pending order moved), `skip` (decided not to copy; see `message`), `adopt` (took over a copy it found on the follower after a restart), `place` (placed a pending order for the master''s) or `cancel` (cancelled one).'
        ok:
          type: boolean
          description: Whether it worked.
        message:
          type: string
          example: Opened 0.20 lots XAUUSD
        detail:
          type: object
          additionalProperties: true
          description: The request and the terminal's answer. Keys vary by action, for example `symbol`, `side`, `volume`, `price`, `ticket`, `stopLoss`, `takeProfit`, `retcode` and `outcome`.
          example:
            symbol: XAUUSD
            side: buy
            volume: 0.2
            ticket: 99120443
        received_at:
          type: string
          description: When the engine heard about the master's change.
          format: date-time
          example: '2026-10-25T14:03:51.204Z'
        engine_ms:
          type:
          - number
          - 'null'
          description: The engine's own time to the order going out.
        execution_ms:
          type:
          - number
          - 'null'
          description: The follower broker's time to answer the order.
        total_ms:
          type:
          - number
          - 'null'
          description: Both together.
      description: One thing the copier engine did, or decided not to do, on a follower.
      required:
      - id
      - object
      - follower_id
      - account_id
      - master_ticket
      - action
      - ok
      - message
      - detail
      - received_at
      - engine_ms
      - execution_ms
      - total_ms
    Problem:
      type: object
      properties:
        type:
          type: string
          description: Where this code is documented.
          format: uri
        title:
          type: string
          description: A short summary of the code.
        status:
          type: integer
          description: The HTTP status, repeated.
        code:
          type: string
          enum:
          - validation_failed
          - invalid_json
          - invalid_cursor
          - invalid_credentials
          - server_not_found
          - already_connected
          - proxy_unreachable
          - connect_rejected
          - authentication_required
          - invalid_api_key
          - api_key_revoked
          - insufficient_scope
          - plan_limit_reached
          - not_found
          - method_not_allowed
          - not_acceptable
          - account_in_use
          - account_not_released
          - unsupported_media_type
          - rate_limited
          - internal_error
          - close_failed
          - disconnect_failed
          - terminal_unreachable
          - terminal_unavailable
          - connect_unavailable
          - terminal_timeout
          description: What went wrong. Branch on this, not on `title` or `detail`.
        detail:
          type: string
          description: What went wrong in this case.
        errors:
          type: array
          description: 'Only for `validation_failed`: one entry per problem.'
          items:
            type: object
            properties:
              path:
                type: string
                description: JSON Pointer to the field, such as `/lot_value` (`/close_positions` for a query parameter); `""` for the request as a whole.
                example: /lot_value
              code:
                type: string
                description: 'A stable code: ours (`already_connected`, `account_released`, `account_not_connected`, `account_is_master`, `account_is_follower`, `already_following`, `self_copy`, `read_only_account`, `netting_account`, `automated_trading_off`, `immutable`, `unknown_field`) or a generic one such as `required`, `invalid`, `invalid_choice` or `does_not_exist`.'
                example: invalid
              message:
                type: string
                example: Use a number above 0 and up to 1000.
            required:
            - path
            - code
            - message
        request_id:
          type: string
          example: b7c1e2d4-5f6a-4b8c-9d0e-1f2a3b4c5d6e
        doc_url:
          type: string
          description: Same as `type`.
          format: uri
      description: RFC 9457 problem details, served as `application/problem+json`.
      required:
      - type
      - title
      - status
      - code
      - detail
      - request_id
      - doc_url
    CopyEventList:
      type: object
      properties:
        object:
          type: string
          enum:
          - list
          description: Always `list`.
        data:
          type: array
          items:
            $ref: '#/components/schemas/CopyEvent'
          description: Newest first.
        has_more:
          type: boolean
          description: 'Whether there''s another page: pass `next_cursor` as `cursor`.'
        next_cursor:
          type:
          - string
          - 'null'
          description: The cursor of the next page; null on the last one.
      required:
      - object
      - data
      - has_more
      - next_cursor
  parameters:
    Limit:
      name: limit
      in: query
      description: Items per page, 1 to 100 (default 50).
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 50
    FollowerIdFilter:
      name: follower_id
      in: query
      description: Only this follower's events.
      schema:
        type: string
        format: uuid
        example: 9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d
    CopierId:
      name: copier_id
      in: path
      required: true
      description: The copier's ID.
      schema:
        type: string
        format: uuid
        example: 3d2c1b0a-9f8e-4d7c-8b6a-5f4e3d2c1b0a
    Cursor:
      name: cursor
      in: query
      description: The `next_cursor` of the previous page. Leave it out for the first page.
      schema:
        type: string
  headers:
    RateLimit-Policy:
      description: The key's limit and window in seconds.
      schema:
        type: string
        example: 120;w=60
    X-Request-Id:
      description: The request's ID, an opaque string, also in error bodies. Include it in support requests. An `X-Request-Id` you send is replaced.
      schema:
        type: string
        example: b7c1e2d4-5f6a-4b8c-9d0e-1f2a3b4c5d6e
    RateLimit:
      description: What's left of the limit, and seconds until the window has room again.
      schema:
        type: string
        example: limit=120, remaining=119, reset=60
    Retry-After:
      description: Seconds to wait before trying again.
      schema:
        type: integer
        example: 21
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      bearerFormat: att_…
      description: '`Authorization: Bearer att_…`'
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: For tools that can only set a custom header.
externalDocs:
  description: Documentation
  url: https://algotradertools.com/docs