> ## Documentation Index > Fetch the complete documentation index at: https://rubie.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Get credential session > Poll a credential session until a vaulted credential is ready. Returns the current session projection. Poll while `status` is `pending` (or any status you do not recognize). Persist `credential_id` only when `status` is `completed`. ```bash theme={null} curl -s "$RUBIE_API_URL/api/v1/credential-sessions/sess_..." \ -H "Authorization: Bearer $RUBIE_API_KEY" ``` ## Status values | Status | Meaning | | ----------- | ---------------------------------------------------------- | | `pending` | End user has not finished the hosted form | | `completed` | Terminal and usable — `credential_id` is present; store it | | `expired` | Terminal and not usable — create a new session | Treat `status` as an open string set. Additional non-terminal values may appear later (for example while Rubie verifies the credential). Keep polling on unrecognized values; only branch on the three above. ## Notes * `hosted_url` is present while the session is pending and cleared afterward. * `credential_id` is `null` until `completed`. Do not persist an id read from any other status. * If you used `return_url`, call this endpoint on the redirect landing page to retrieve and save the completed session's `credential_id`. See [Hosted credential collection](/guides/hosted-credential-collection). ## OpenAPI ````yaml GET /credential-sessions/{id} openapi: 3.0.3 info: title: Rubie API version: 1.0.0 description: > Collect end-user credentials through a Rubie-hosted form, then run Rubie Blueprints against them asynchronously. This API is deliberately thin. Rubie does not model your domain: what a Blueprint accepts as input, what it does with a connected system, and what it produces are all defined by that Blueprint's configuration. The endpoints below are the transport around it. All endpoints require bearer authentication. Responses use opaque prefixed IDs (`cred_`, `sess_`, `ecs_`, `strat_`, `run_`, `bp_`), snake_case fields, and a single top-level error envelope — never a `success` wrapper. servers: - url: https://app.rubiehq.com/api/v1 description: Production security: - BearerAuth: [] tags: - name: Credential Sessions description: Start and poll Rubie-hosted credential collection flows. - name: Embedded Credential Sessions description: Embed a Blueprint picker and credential capture flow in your product. - name: Credentials description: Revoke vaulted credentials. - name: Blueprints description: Trigger a Rubie Blueprint run. - name: Blueprint Runs description: Poll run status and retrieve completed outputs. paths: /credential-sessions/{id}: get: tags: - Credential Sessions summary: Get credential session status operationId: getCredentialSession parameters: - name: id in: path required: true schema: type: string example: sess_MQ responses: '200': description: Session content: application/json: schema: $ref: '#/components/schemas/CredentialSession' examples: pending: summary: Waiting on the end user value: id: sess_MQ status: pending hosted_url: https://app.rubiehq.com/credential-collect/abc123 return_url: https://app.example.com/settings/integrations/connected strategy_id: strat_NQ credential_id: null expires_at: '2026-08-07T17:00:00.000Z' completed_at: null created_at: '2026-07-31T17:00:00.000Z' completed: summary: Credential ready value: id: sess_MQ status: completed hosted_url: null return_url: https://app.example.com/settings/integrations/connected strategy_id: strat_NQ credential_id: cred_NDc expires_at: '2026-08-07T17:00:00.000Z' completed_at: '2026-07-31T17:05:00.000Z' created_at: '2026-07-31T17:00:00.000Z' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' components: schemas: CredentialSession: type: object required: - id - status - strategy_id - expires_at - created_at properties: id: type: string example: sess_MQ status: $ref: '#/components/schemas/CredentialSessionStatus' hosted_url: type: string nullable: true description: >- Rubie-hosted form URL. Open for the end user while status is pending. return_url: type: string format: uri nullable: true description: > Customer URL supplied when the session was created. After collection, Rubie redirects here with `session_id` appended as a query parameter. strategy_id: type: string example: strat_NQ credential_id: type: string nullable: true example: cred_NDc description: > Present only when `status` is `completed`, and stable for the life of the credential. Retain it against your user record. Do not persist an id read from a session in any other status. expires_at: type: string format: date-time completed_at: type: string format: date-time nullable: true created_at: type: string format: date-time CredentialSessionStatus: type: string description: > Lifecycle status of the session. `completed` always means terminal and usable: the credential is vaulted and may be passed to a run. `expired` is terminal and not usable. `pending` means the end user has not finished the hosted form yet. Treat this as an open string set rather than a fixed enum. Additional non-terminal statuses may be introduced between collection and `completed` — for example while Rubie verifies the credential against the target system. Keep polling on any status you do not recognise, and only branch on the three values above. Code written as `if (status === "completed") { save(credential_id) }` stays correct. enum: - pending - completed - expired ErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/Error' Error: type: object required: - type - message properties: type: type: string enum: - authentication_error - authorization_error - not_found - validation_error - conflict - rate_limit_exceeded - internal_error message: type: string details: type: array items: $ref: '#/components/schemas/ErrorDetail' ErrorDetail: type: object required: - message properties: message: type: string code: type: string nullable: true field: type: string nullable: true responses: Unauthorized: description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' NotFound: description: Resource not found in this account content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: APIKey description: Your Rubie API key as a bearer token. ````