creatordb-app General Operations API

openapi: 3.2.0
info:
  version: 1.0.0
  title: CreatorDB Headless API V3 General Operations API
  description: '# CreatorDB Headless API V3'
  contact:
    name: CreatorDB
    url: https://www.creatordb.app
    email: support@creatordb.app
  license:
    url: http://www.apache.org/licenses/LICENSE-2.0.html
    name: Apache 2.0
servers:
- url: https://apiv3.creatordb.app
  description: Production Environment (CreatorDB Headless API V3)
security:
- ApiKeyAuth: []
tags:
- name: General Operations
paths:
  /usage:
    get:
      tags:
      - General Operations
      summary: Get API Usage
      description: Retrieve your API usage statistics within the specified date range (maximum 365 days). Defaults to 7 days ago when no start or end dates are provided.
      operationId: getApiUsage
      parameters:
      - name: start
        in: query
        description: Start date, represented as a Unix timestamp in milliseconds. Defaults to 7 days ago.
        required: false
        schema:
          type: string
          examples:
          - '1737312000000'
      - name: end
        in: query
        description: End date, represented as a Unix timestamp in milliseconds. Defaults to current time.
        required: false
        schema:
          type: string
          examples:
          - '1737398400000'
      x-codeSamples:
      - lang: bash
        label: cURL
        source: "curl -X GET \"https://apiv3.creatordb.app/usage\" \\\n  -H \"api-key: <YOUR_API_KEY_HERE>\"\n"
      responses:
        '200':
          description: API credit usage results returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    description: API usage data containing records and count.
                    properties:
                      records:
                        type: array
                        description: API usage records for the requested date range.
                        items:
                          type: object
                          properties:
                            date:
                              type: string
                              description: Date in YYYYMMDD format (UTC±0).
                              pattern: ^\d{8}$
                              examples:
                              - '20260120'
                            requestCount:
                              type: integer
                              description: Total number of API requests for this API key.
                              minimum: 0
                              examples:
                              - 47
                            totalQuotaUsed:
                              type: number
                              description: Total credits consumed for this API key.
                              minimum: 0
                              examples:
                              - 47
                            totalQuotaAdded:
                              type: number
                              description: Total credits added by admin custom operations for this API key.
                              minimum: 0
                              examples:
                              - 12
                            endpoints:
                              type: object
                              description: Request count and quota usage per endpoint.
                              additionalProperties:
                                type: object
                                properties:
                                  count:
                                    type: integer
                                    description: Number of requests made to this endpoint, including both full and fractional requests.
                                    minimum: 0
                                  quotaUsed:
                                    type: number
                                    description: Total API credits consumed by this endpoint.
                                    minimum: 0
                                  quotaAdded:
                                    type: number
                                    description: Total API credits added by this endpoint.
                                    minimum: 0
                                  fractional:
                                    type: object
                                    description: Portion of this endpoint's total `count` and `quotaUsed` attributable to fractional calls, which return only the fields the caller requested. Absent when no fractional calls were made to this endpoint on this day.
                                    properties:
                                      count:
                                        type: integer
                                        description: Number of fractional requests made to this endpoint.
                                        minimum: 0
                                      quotaUsed:
                                        type: number
                                        description: API credits consumed by fractional requests to this endpoint.
                                        minimum: 0
                                    required:
                                    - count
                                    - quotaUsed
                                required:
                                - count
                                - quotaUsed
                                - quotaAdded
                              examples:
                              - searchInstagram:
                                  count: 12
                                  quotaUsed: 12
                                  quotaAdded: 0
                                getInstagramProfile:
                                  count: 8
                                  quotaUsed: 8
                                  quotaAdded: 0
                                getYoutubeProfile:
                                  count: 15
                                  quotaUsed: 22
                                  quotaAdded: 0
                                  fractional:
                                    count: 9
                                    quotaUsed: 4
                                custom:
                                  count: 3
                                  quotaUsed: 5
                                  quotaAdded: 12
                            platforms:
                              type: object
                              description: Number of requests per social media platform. Empty when no platform-specific calls were made.
                              additionalProperties:
                                type: integer
                                minimum: 0
                              default: {}
                              examples:
                              - instagram: 20
                                tiktok: 10
                                youtube: 17
                            quotaByPlatform:
                              type: object
                              description: API credits consumed per social media platform. Empty when no platform-specific calls were made.
                              additionalProperties:
                                type: number
                                minimum: 0
                              default: {}
                              examples:
                              - instagram: 20
                                tiktok: 10
                                youtube: 17
                          required:
                          - date
                          - requestCount
                          - totalQuotaUsed
                          - totalQuotaAdded
                          - endpoints
                      count:
                        type: integer
                        description: Total number of records returned.
                        minimum: 0
                        examples:
                        - 7
                      key:
                        type: object
                        description: The calling API key's spendlimit status.
                        properties:
                          creditLimit:
                            type:
                            - number
                            - 'null'
                            description: The lifetime credit limit for this API key, in credits. `null` when the key has no limit.
                            examples:
                            - 5000
                          creditsRemaining:
                            type:
                            - number
                            - 'null'
                            description: Remaining credits this API key can spend before reaching its limit, calculated as credit limit minus cumulative spend. A negative value means cumulative spend has exceeded the limit, and further requests are rejected. `null` when the key has no limit of its own, in which case spending is bounded only by the account's available credits.
                            examples:
                            - 4975
                            - -1205
                            - null
                          active:
                            type: boolean
                            description: Whether this API key is currently active.
                            examples:
                            - true
                        required:
                        - creditLimit
                        - creditsRemaining
                        - active
                    required:
                    - records
                    - count
                    - key
                  creditsUsed:
                    type: number
                    description: Total number of API credits consumed across all requests in this session.
                    examples:
                    - 1
                  creditsAvailable:
                    type: number
                    description: 'Number of API credits remaining. Calculated as: `planCreditsAvailable` + `purchasedCreditsAvailable`.'
                    examples:
                    - -1
                  planCreditsAvailable:
                    type: number
                    description: Remaining plan credits after this request, in credits.
                    examples:
                    - 900
                  purchasedCreditsAvailable:
                    type: number
                    description: Remaining purchased credits after this request, in credits.
                    examples:
                    - 75
                  keyCreditsAvailable:
                    type: number
                    description: Remaining credits this API key can spend after this request, before reaching its spend limit. Present only when the key has a spend limit.
                    examples:
                    - 4975
                  traceId:
                    type: string
                    description: Unique trace ID for each request.
                    examples:
                    - f8e4a3b2c1d0e9f8a7b6c5d4e3f2a1b0
                  timestamp:
                    type: integer
                    description: Time the response was generated, represented as a Unix timestamp in milliseconds.
                    examples:
                    - 1750732453635
                  errorCode:
                    type: string
                    description: Error code returned if the request fails. Empty if the request is successful.
                    examples:
                    - ''
                  errorDescription:
                    type: string
                    description: Description of the error. Empty if the request is successful.
                    examples:
                    - ''
                  success:
                    type: boolean
                    description: '`true` if the request is successful.'
                    examples:
                    - true
                required:
                - data
                - traceId
                - timestamp
                - errorCode
                - errorDescription
                - success
                - creditsUsed
                - creditsAvailable
                - planCreditsAvailable
                - purchasedCreditsAvailable
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                type: object
                title: ValidationErrorResponse
                properties:
                  success:
                    const: false
                  error:
                    type: string
                  message:
                    type: string
                  timestamp:
                    type: integer
                required:
                - success
                - error
                - message
                - timestamp
              examples:
                invalid date range:
                  summary: Date range exceeds 365 days
                  value:
                    success: false
                    error: VALIDATION_ERROR
                    message: The 'start' and 'end' date range cannot exceed 365 days.
                    timestamp: 1770099403116
        '429':
          description: Exceeded quota or rate limit.
          content:
            application/json:
              schema:
                type: object
                title: QuotaErrorResponse
                properties:
                  success:
                    const: false
                  error:
                    type: string
                  message:
                    type: string
                  remainingPlanCredit:
                    type: number
                required:
                - success
                - error
                - message
                - remainingPlanCredit
              examples:
                rate limited:
                  summary: Rate limit exceeded
                  value:
                    success: false
                    error: RATE_LIMIT_EXCEEDED
                    message: Too many requests. Please try again later.
                quota exceeded:
                  summary: Credit quota exceeded
                  value:
                    success: false
                    error: QUOTA_EXCEEDED
                    message: Not enough credits to complete this request.
      security:
      - ApiKeyAuth: []
      servers:
      - url: https://apiv3.creatordb.app
        description: Production Environment (CreatorDB Headless API V3)
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: The valid CreatorDB API key for authentication.
      name: api-key
      in: header