Skip to main content

Get a Connector Offsets

GET 
/connect/v1/environments/:environment_id/clusters/:kafka_cluster_id/connectors/:connector_name/offsets

General Availability

Get the current offsets for the connector. The offsets provide information on the point in the source system, from which the connector is pulling in data. The offsets of a connector are continuously observed periodically and are queryable via this API.

Request​

Responses​

Connector Offsets.

OpenAPI definition (YAML) 
paths:
  /connect/v1/environments/{environment_id}/clusters/{kafka_cluster_id}/connectors/{connector_name}/offsets:
    get:
      x-lifecycle-stage: General Availability
      operationId: getConnectv1ConnectorOffsets
      description: "[![General Availability](https://img.shields.io/badge/Lifecycle%20Stage-General%20Availability-%2345c6e8)](#section/Versioning/API-Lifecycle-Policy)\n\
        \nGet the current offsets for the connector. The offsets provide information on the point in the\
        \ source system, \nfrom which the connector is pulling in data. The offsets of a connector are\
        \ continuously observed periodically and are queryable via this API."
      tags:
      - Offsets (connect/v1)
      security:
      - cloud-api-key: []
      - confluent-sts-access-token: []
      responses:
        '200':
          description: Connector Offsets.
          content:
            application/json:
              schema:
                type: object
                description: Offsets for a connector
                properties:
                  name:
                    type: string
                    description: The name of the connector.
                  id:
                    type: string
                    description: The ID of the connector.
                  offsets:
                    type: array
                    description: Array of offsets which are categorised into partitions.
                    items:
                      type: object
                      properties:
                        partition:
                          type: object
                          additionalProperties: true
                          description: "The partition information. For sink connectors this is the kafka\
                            \ topic and \npartition. For source connectors this is depends on the partitions\
                            \ defined by the \nsource connector. For example, the table which this task\
                            \ is pulling data from in a\nJDBC based MySQL source connector.\nPlease refer\
                            \ to the [documentation](https://docs.confluent.io/cloud/current/connectors/offsets.html#manage-offsets-for-fully-managed-connectors-in-ccloud)\
                            \ for \nmore information."
                        offset:
                          type: object
                          additionalProperties: true
                          description: "The offset of the partition. For sink connectors this is the kafka\
                            \ offset. For \nsource connectors this is depends on the offset defined by\
                            \ the source connector. \nFor example, the timestamp and incrementing column\
                            \ info in a table, for a JDBC based \nMySQL source connector.\nPlease refer\
                            \ to the [documentation](https://docs.confluent.io/cloud/current/connectors/offsets.html#manage-offsets-for-fully-managed-connectors-in-ccloud)\
                            \ for \nmore information."
                    title: connect.v1.Offsets
                  metadata:
                    type: object
                    description: Metadata of the connector offset.
                    properties:
                      observed_at:
                        type: string
                        format: date-time
                        example: '2024-02-20 15:14:19+00:00'
                        readOnly: true
                        description: The time at which the offsets were observed. The time is in UTC,
                          ISO 8601 format.
                title: connect.v1.ConnectorOffsets
              examples:
                sink:
                  value:
                    id: lcc-as341
                    name: MysqlSinkConnector
                    offsets:
                    - partition:
                        kafka_partition: 0
                        kafka_topic: topic_A
                      offset:
                        kafka_offset: 20032323
                    - partition:
                        kafka_partition: 1
                        kafka_topic: topic_B
                      offset:
                        kafka_offset: 20032322
                    metadata:
                      observed_at: '2024-02-20 15:14:19+00:00'
                source:
                  value:
                    id: lcc-21sdda
                    name: MysqlSourceConnector
                    offsets:
                    - partition:
                        protocol: 1
                        table: sourcedb.sourcetable
                      offset:
                        timestamp_nanos: 0
                        incrementing: 3
                        timestamp: 1699142400000
                    metadata:
                      observed_at: '2024-02-20 15:14:19+00:00'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    description: Connector Error with error code and message.
                    properties:
                      code:
                        type: integer
                        description: Error code for the type of error
                      message:
                        type: string
                        description: Human readable error message
                title: connect.v1.ConnectorError
              example:
                error:
                  code: 400
                  message: Bad Request
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    description: Connector Error with error code and message.
                    properties:
                      code:
                        type: integer
                        description: Error code for the type of error
                      message:
                        type: string
                        description: Human readable error message
                title: connect.v1.ConnectorError
              example:
                error:
                  code: 401
                  message: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    description: Connector Error with error code and message.
                    properties:
                      code:
                        type: integer
                        description: Error code for the type of error
                      message:
                        type: string
                        description: Human readable error message
                title: connect.v1.ConnectorError
              example:
                error:
                  code: 403
                  message: Forbidden
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    description: Connector Error with error code and message.
                    properties:
                      code:
                        type: integer
                        description: Error code for the type of error
                      message:
                        type: string
                        description: Human readable error message
                title: connect.v1.ConnectorError
              example:
                error:
                  code: 404
                  message: resource not found
        '429':
          description: Rate Limit Exceeded
          headers:
            X-Request-Id:
              schema:
                type: string
              description: The unique identifier for the API request.
            X-RateLimit-Limit:
              schema:
                type: integer
              description: The maximum number of requests you're permitted to make per time period.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: The number of requests remaining in the current rate limit window.
            X-RateLimit-Reset:
              schema:
                type: integer
              description: "The relative time in seconds until the current rate-limit window resets. \
                \ \n  \n**Important:** This differs from Github and Twitter's same-named header which\
                \ uses UTC epoch seconds. We use relative time to avoid client/server time synchronization\
                \ issues."
            Retry-After:
              schema:
                type: integer
              description: The number of seconds to wait until the rate limit window resets. Only sent
                when the rate limit is reached.
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    description: Connector Error with error code and message.
                    properties:
                      code:
                        type: integer
                        description: Error code for the type of error
                      message:
                        type: string
                        description: Human readable error message
                title: connect.v1.ConnectorError
              example:
                error:
                  code: 500
                  message: Oops, something went wrong
      parameters:
      - name: connector_name
        in: path
        schema:
          type: string
        required: true
        description: The unique name of the connector.
      - name: environment_id
        in: path
        schema:
          type: string
        required: true
        description: The unique identifier of the environment this resource belongs to.
      - name: kafka_cluster_id
        in: path
        schema:
          type: string
        required: true
        description: The unique identifier for the Kafka cluster.
      servers:
      - url: https://api.confluent.cloud
        description: Confluent Cloud API