segment

Segment Pixel Tracking API

The Segment Pixel Tracking API provides a way to collect analytics data using image pixel requests, which is useful in environments where JavaScript cannot execute, such as email clients. It supports identify, track, page, screen, group, and alias calls through pixel endpoints under the api.segment.io domain. This API is particularly suited for tracking email opens, ad impressions, and other contexts where embedding a tracking pixel is the only viable data collection method.

GitHub OpenAPI

Documentation

📖
Documentation
https://www.twilio.com/docs/segment/connections/sources/catalog/libraries/server/pixel-tracking-api

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/segment/refs/heads/main/openapi/segment-pixel-tracking-api-openapi.yml

Other Resources

🔗
APIsJSON
https://raw.githubusercontent.com/api-evangelist/segment/refs/heads/main/apis.yml

OpenAPI Specification

segment-pixel-tracking-api-openapi.yml Raw ↑ 
openapi: 3.1.0
info:
  title: Segment Config Alias Pixel Tracking API
  description: The Segment Config API allows programmatic management of Segment workspaces, sources, destinations, and other configuration resources. It provides endpoints to list workspace sources and destinations, create or delete destinations, and manage tracking plans. As of early 2024, Segment has stopped issuing new Config API tokens and recommends migrating to the Public API for access to the latest features. The Config API remains functional for existing users but is no longer actively developed.
  version: 1.0.0
  contact:
    name: Segment Support
    url: https://segment.com/help/
  termsOfService: https://segment.com/legal/terms/
  x-status: deprecated
servers:
- url: https://platform.segmentapis.com/v1beta
  description: Production Server (v1beta)
security:
- bearerAuth: []
tags:
- name: Pixel Tracking
  description: Pixel-based tracking endpoints that accept data via query parameters and return a transparent 1x1 GIF image. All data is passed as a base64-encoded JSON object in the data query parameter.
paths:
  /pixel/identify:
    get:
      operationId: pixelIdentify
      summary: Identify via pixel
      description: Associates a user with traits via a tracking pixel request. The data parameter should contain a base64-encoded JSON object with the identify payload. Always returns a 200 response with a transparent GIF, even on errors.
      tags:
      - Pixel Tracking
      parameters:
      - $ref: '#/components/parameters/Data'
      responses:
        '200':
          description: Returns a transparent 1x1 GIF image. The response is always 200 regardless of whether the data was valid.
          content:
            image/gif:
              schema:
                type: string
                format: binary
  /pixel/track:
    get:
      operationId: pixelTrack
      summary: Track via pixel
      description: Records an event via a tracking pixel request. The data parameter should contain a base64-encoded JSON object with the track payload including the required event field.
      tags:
      - Pixel Tracking
      parameters:
      - $ref: '#/components/parameters/Data'
      responses:
        '200':
          description: Returns a transparent 1x1 GIF image.
          content:
            image/gif:
              schema:
                type: string
                format: binary
  /pixel/page:
    get:
      operationId: pixelPage
      summary: Page via pixel
      description: Records a page view via a tracking pixel request. The data parameter should contain a base64-encoded JSON object with the page payload.
      tags:
      - Pixel Tracking
      parameters:
      - $ref: '#/components/parameters/Data'
      responses:
        '200':
          description: Returns a transparent 1x1 GIF image.
          content:
            image/gif:
              schema:
                type: string
                format: binary
  /pixel/screen:
    get:
      operationId: pixelScreen
      summary: Screen via pixel
      description: Records a screen view via a tracking pixel request. The data parameter should contain a base64-encoded JSON object with the screen payload.
      tags:
      - Pixel Tracking
      parameters:
      - $ref: '#/components/parameters/Data'
      responses:
        '200':
          description: Returns a transparent 1x1 GIF image.
          content:
            image/gif:
              schema:
                type: string
                format: binary
  /pixel/group:
    get:
      operationId: pixelGroup
      summary: Group via pixel
      description: Associates a user with a group via a tracking pixel request. The data parameter should contain a base64-encoded JSON object with the group payload including the required groupId field.
      tags:
      - Pixel Tracking
      parameters:
      - $ref: '#/components/parameters/Data'
      responses:
        '200':
          description: Returns a transparent 1x1 GIF image.
          content:
            image/gif:
              schema:
                type: string
                format: binary
  /pixel/alias:
    get:
      operationId: pixelAlias
      summary: Alias via pixel
      description: Merges two user identities via a tracking pixel request. The data parameter should contain a base64-encoded JSON object with the alias payload including previousId and userId.
      tags:
      - Pixel Tracking
      parameters:
      - $ref: '#/components/parameters/Data'
      responses:
        '200':
          description: Returns a transparent 1x1 GIF image.
          content:
            image/gif:
              schema:
                type: string
                format: binary
components:
  parameters:
    Data:
      name: data
      in: query
      required: true
      description: A base64-encoded JSON object containing the call payload. Base64 encoding is optional but recommended to prevent special character manipulation by browsers or intermediaries. The JSON object must include a writeKey field for authentication and either a userId or anonymousId for user identification.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Segment Config API access token. Note that as of early 2024, Segment has stopped issuing new Config API tokens.
externalDocs:
  description: Segment Config API Documentation
  url: https://segment.com/docs/api/config-api/