> ## Documentation Index > Fetch the complete documentation index at: https://docs.shelfforce.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get analysis > Retrieves the current state and results of a shelf analysis. While `status` is `processing`, the `products` array may be empty or partial. Once `completed`, all detected products are included. ## OpenAPI ````yaml /openapi.json get /api/v1/analyses/{id} openapi: 3.1.0 info: title: Shelfforce API version: 1.0.0 description: >- Shelfforce turns shelf photos into structured retail data. Submit images for AI-powered shelf analysis, manage tasks and inventory, and retrieve compliance and share-of-shelf reports. All API requests require a Bearer token (API key with `sf_live_` prefix). Rate limits are enforced per tier using a fixed 60-second window. Idempotency is supported on POST and PATCH via the `Idempotency-Key` header (24h TTL). 1 credit = 1 image analysis. Batch submissions consume 1 credit per image (max batch size depends on plan tier: 20-200). Tag analyses with `externalId` and `metadata` for B2B tracking, and use `callbackUrl` for per-request completion notifications. termsOfService: https://shelfforce.ai/terms contact: name: Shelfforce Support url: https://shelfforce.ai/support email: hey@shelfforce.ai license: name: Proprietary url: https://shelfforce.ai/terms servers: - url: https://shelfforce.ai description: Production security: - bearerAuth: [] tags: - name: Analyses description: Submit images for AI shelf analysis and retrieve results. - name: Products description: Browse products detected across analyses. - name: Places description: Manage store locations tied to your organisation. - name: Tasks description: Create and manage field data-collection tasks. - name: Inventory description: Maintain a master catalogue of expected SKUs. - name: Reports description: 'Aggregated analytics: share of shelf and store performance.' - name: Webhooks description: Register endpoints to receive real-time event notifications. - name: Usage description: Check credit balance, plan details, and rate-limit status. - name: Orders description: Create and manage purchase orders with line items. - name: Accounts description: Manage brand, supplier, distributor, and partner accounts. - name: Alerts description: >- Read and manage system-generated alerts. Alerts are created automatically — no POST endpoint. - name: Members description: >- List, invite, update, and remove organisation members. Admin role required for writes. paths: /api/v1/analyses/{id}: get: tags: - Analyses summary: Get analysis description: >- Retrieves the current state and results of a shelf analysis. While `status` is `processing`, the `products` array may be empty or partial. Once `completed`, all detected products are included. operationId: getAnalysis parameters: - name: id in: path required: true description: Analysis ID returned from the create or batch endpoint. schema: type: string examples: - an_g7h8j9k0 responses: '200': description: Analysis details with detected products. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/Analysis' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' components: headers: X-RateLimit-Limit: description: Maximum number of requests allowed in the current 60-second window. schema: type: integer examples: - 120 X-RateLimit-Remaining: description: Number of requests remaining in the current window. schema: type: integer examples: - 117 X-RateLimit-Reset: description: Unix timestamp (seconds) when the current rate-limit window resets. schema: type: integer examples: - 1740300060 X-Request-Id: description: Unique identifier for this request. Include in support tickets. schema: type: string format: uuid examples: - 550e8400-e29b-41d4-a716-446655440000 schemas: Analysis: type: object required: - id - status - totalRuns - completedRuns - failedRuns - products - productCount - createdAt properties: id: type: string description: Unique analysis identifier. examples: - an_g7h8j9k0 status: type: string enum: - processing - completed - failed description: Current processing status. examples: - completed externalId: type: - string - 'null' description: Your external reference ID, if provided at submission. examples: - customer-123 metadata: type: - object - 'null' description: Arbitrary metadata provided at submission. examples: - store: store-42 aisle: '3' placeId: type: - string - 'null' description: Associated place ID, if provided. examples: - pl_abc123 taskId: type: - string - 'null' description: Associated task ID, if provided. examples: - tsk_xyz789 totalRuns: type: integer description: Total number of image runs in this analysis. examples: - 1 completedRuns: type: integer description: Number of successfully completed runs. examples: - 1 failedRuns: type: integer description: Number of failed runs. examples: - 0 products: type: array items: $ref: '#/components/schemas/Product' description: Detected products. Empty while status is `processing`. productCount: type: integer description: Total number of detected products. examples: - 12 createdAt: type: string format: date-time description: Timestamp when the analysis was submitted. examples: - '2026-02-23T10:30:00Z' completedAt: type: - string - 'null' format: date-time description: Timestamp when the analysis finished. Null while processing. examples: - '2026-02-23T10:32:00Z' Product: type: object required: - id - brand - description - units properties: id: type: string description: Unique product detection identifier. examples: - prd_k1l2m3 sku: type: - string - 'null' description: Matched SKU code from inventory, if identified. examples: - CC-330ML-CAN brand: type: string description: Detected brand name. examples: - Coca-Cola description: type: string description: Product description as detected on shelf. examples: - Coca-Cola Original 330ml Can category: type: - string - 'null' description: Product category. examples: - Beverages subcategory: type: - string - 'null' description: Product subcategory. examples: - Carbonated Soft Drinks price: type: - number - 'null' description: Detected shelf price. examples: - 1.49 discountedPrice: type: - number - 'null' description: Discounted/promotional price if on sale. examples: - 1.19 currency: type: - string - 'null' description: ISO 4217 currency code. examples: - USD onSale: type: - boolean - 'null' description: Whether the product is currently on sale. examples: - false units: type: integer description: Number of facings (visible units) on the shelf. minimum: 1 examples: - 4 confidence: type: string enum: - low - medium - high description: Detection confidence level. examples: - high shelfPosition: type: - string - 'null' enum: - top - middle - bottom - null description: Vertical row position on the shelf. examples: - top shelfSection: type: - string - 'null' enum: - left - center - right - null description: Horizontal section position on the shelf. examples: - center fixtureType: type: - string - 'null' description: >- Type of retail fixture the product was detected on (shelf, fridge, floor-display, etc.). examples: - fridge sizeValue: type: - number - 'null' description: Product size value extracted from label. examples: - 330 sizeUnit: type: - string - 'null' description: Product size unit (ml, L, g, kg, oz, pack, ct, etc.). examples: - ml matchedInventorySku: type: - string - 'null' description: Matched SKU from your inventory catalog, if identified. examples: - CC-330ML-CAN matchStatus: type: - string - 'null' enum: - matched - ambiguous - unmatched - null description: Whether this product was matched to your inventory. examples: - matched responses: Unauthorized: description: Authentication failed. Provide a valid API key as a Bearer token. headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string enum: - AUTH_REQUIRED - INVALID_API_KEY examples: - INVALID_API_KEY message: type: string examples: - The provided API key is invalid or has been revoked. NotFound: description: The requested resource does not exist. headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string const: NOT_FOUND examples: - NOT_FOUND message: type: string examples: - Analysis 'an_g7h8j9k0' not found. RateLimited: description: Too many requests. Wait until the rate-limit window resets. headers: Retry-After: description: Seconds until the rate-limit window resets. schema: type: integer examples: - 12 X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string const: RATE_LIMITED examples: - RATE_LIMITED message: type: string examples: - Rate limit exceeded. Retry after 12 seconds. InternalError: description: An unexpected server error occurred. headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string const: INTERNAL_ERROR examples: - INTERNAL_ERROR message: type: string examples: - >- An unexpected error occurred. Please try again or contact support with request ID. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: >- API key with `sf_live_` prefix. Pass as `Authorization: Bearer sf_live_...` ````