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

# Retrieve saved read progress or export its rows

> Retrieves only this grant's unexpired job, with authorization checked again. No new bank request is made. JSON contains state, pages, nextCursor, rowsComplete, fetchedAt, intent (null when not supplied), and an error or partial-result reason when applicable.



## OpenAPI

````yaml /api-reference/openapi.yaml get /connect/reads/{runId}
openapi: 3.0.3
info:
  title: Payman Connect API
  version: 0.1.0
  description: >-
    The HTTP contract behind Payman Connect: exchange a customer's consent for a
    grant, send actions against the accounts it reaches, and follow an approval
    to its receipt. Every call carries your app key, and every call after the
    exchange carries the grant. Non-2xx responses share one `ApiError` envelope.
    Most integrations never write these calls: the SDK speaks them for you.
servers:
  - url: https://paygent-cloud-server-production.up.railway.app
    description: Current hosted Railway deployment
  - url: http://localhost:8891
    description: A local stack
security:
  - bearerAuth: []
tags:
  - name: Connect
    description: >-
      Third-party access. A registered app presents its app key together with a
      grant token its customer consented to; the pair reaches exactly the one
      deployment the grant names, and nothing else on this API.
paths:
  /connect/reads/{runId}:
    get:
      tags:
        - Connect
      summary: Retrieve saved read progress or export its rows
      description: >-
        Retrieves only this grant's unexpired job, with authorization checked
        again. No new bank request is made. JSON contains state, pages,
        nextCursor, rowsComplete, fetchedAt, intent (null when not supplied),
        and an error or partial-result reason when applicable.
      operationId: getStructuredRead
      parameters:
        - in: path
          name: runId
          required: true
          schema:
            type: string
            format: uuid
        - in: query
          name: format
          schema:
            type: string
            enum:
              - json
              - csv
            default: json
      responses:
        '200':
          description: Stored progress, including explicit completeness and freshness.
          headers:
            x-payman-read-state:
              description: CSV job state
              schema:
                type: string
                enum:
                  - completed
                  - partial
                  - failed
            x-payman-rows-complete:
              description: CSV completeness for the requested account and date scope
              schema:
                type: boolean
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                required:
                  - intent
                properties:
                  intent:
                    $ref: '#/components/schemas/FinancialReadIntent'
                  pages:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                      required:
                        - data
                        - fetchedAt
                      properties:
                        data:
                          type: object
                          additionalProperties: true
                        fetchedAt:
                          type: string
                          format: date-time
                        executionId:
                          type: string
                          description: >-
                            Runtime execution ID for this provider page, when
                            supported.
                        sessionId:
                          type: string
                          description: >-
                            Runtime conversation session grouping pages and
                            attempts for this read job.
            text/csv:
              schema:
                type: string
        '401':
          description: Invalid or expired Connect credentials
        '403':
          description: Connection is no longer authorized
        '404':
          description: Job does not belong to this grant or has expired
        '409':
          description: CSV requested while the job is still running
      security:
        - connectAppKey: []
          connectGrant: []
        - connectGrant: []
components:
  schemas:
    FinancialReadIntent:
      type: object
      nullable: true
      additionalProperties: false
      required:
        - purpose
      description: >-
        Optional caller-supplied context for record keeping. Include the known
        purpose by default, or omit/use null when unknown. This is not an
        instruction or a verified identity. Avoid credentials and full
        conversations. Stored encrypted with the read job for 24 hours; save the
        JSON metadata for longer retention.
      properties:
        purpose:
          type: string
          minLength: 1
          maxLength: 1000
          description: Why the user wants these records.
        taskId:
          type: string
          minLength: 1
          maxLength: 128
          description: >-
            Shared task ID linking related reads, distinct from each read's
            requestId.
        requestedBy:
          type: string
          minLength: 1
          maxLength: 128
          description: >-
            Caller-reported bot or application label. Authentication still
            determines the caller's identity.
  securitySchemes:
    connectAppKey:
      type: apiKey
      in: header
      name: x-paygent-connect-app-key
      description: >-
        A Connect app key (`pgc_app_…`), identifying the registered third-party
        app. Always presented together with `connectGrant` — the pair is one
        credential, and either half alone is refused. Accepted on the
        `/connect/*` surface only.
    connectGrant:
      type: apiKey
      in: header
      name: x-paygent-connect-grant
      description: >-
        A Connect grant token (`pgc_grant_…`): one user's consent for the
        presenting app to reach one deployment. Every failure mode — missing,
        malformed, revoked, expired, or paired with the wrong app key — answers
        the same 401 `invalid_connect_credentials`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.