Overriding Custom Usage on Result Retrieval

Update Usage on Result Retrieval: This guide explains how to override initial API usage by passing custom headers when users call for the result, ensuring precise usage tracking.

MagicAPI now offers a way to override custom usage during result retrieval. This is an extension of the existing custom usage support, designed for scenarios where the actual usage cannot be determined during the initial API request. This is especially useful for use cases like AI agents or background jobs where processing takes time, and the final resource consumption is known only when the results are ready.

This guide covers the two methods for API developers to adjust API usage after a request has been made using MagicAPI. These methods ensure precise tracking of resource consumption, especially when actual usage cannot be determined during the initial request. The two methods are:

1. Overriding Usage on Result Retrieval (using custom headers).

2. Overwriting Usage with the /[apiStoreSlug]/overrideCustomUsage endpoint.

Method 1: Update Usage on Result Retrieval

This method allows API developers to adjust the usage at the time when results are retrieved by the user. It is ideal for use cases where the initial request consumption is uncertain, such as AI agents or background jobs, where the actual resources used become apparent only after processing is completed.

Use Case:

When an API user initiates a job (e.g., starting an AI process), the default usage is recorded as 1 unit. If the job consumes more resources, you can update the usage when the result is retrieved using override headers.

How to Implement:

1. Initiating a Job:

   • When a user calls MagicAPI to start a job, MagicAPI forwards the request to your API and includes a unique x-request-id in the headers.

   • This x-request-id acts as a unique identifier for the request, allowing you to adjust the usage when the job is completed.

2. Overriding Usage on Result Retrieval:

   • Once the job is completed and the user requests the result via a /result or similar endpoint, override the initial usage using the following headers in your response:

     • "override-request-id": "Original-Request-Id"

     • "override-x-magicapi-billing": "UsageAmount"

   • Here:

     • override-request-id: Must match the x-request-id from the original job initiation request.

     • override-x-magicapi-billing: Specifies the updated usage value (e.g., 519 units) based on the actual resources used.

Example:

Step 1: Original Request User starts an API job:

Copy

curl --location 'https://api.magicapi.dev/api/v1/pipfeed/parse/extract' \
--header 'accept: application/json' \
--header 'x-magicapi-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "url": "https://techcrunch.com/2022/04/18/web-scraping-legal-court/"
}'

Headers Sent by MagicAPI to Your API:

Copy

{
  "x-request-id": "f8e1d576-a460-4847-8683-c31b88c4a958",
  "host": "localhost:4000",
  "connection": "keep-alive",
  "accept": "application/json",
  "content-type": "application/json",
  "x-invoke-path": "/api/v1/pipfeed/parse/extract",
  "x-magicapi-user": "cll8kolno0000l808v6p3xvax",
  "x-magicapi-plan": "Private",
  "content-length": "74"
}

Note: The critical header here is "x-request-id".

Step 2: Overriding Usage with Result

When the job completes and the user retrieves the result:

• Include these headers in your response:

Copy

{
  "override-request-id": "f8e1d576-a460-4847-8683-c31b88c4a958",
  "override-x-magicapi-billing": "API=519;"
}

This response updates the recorded usage for x-request-id f8e1d576-a460-4847-8683-c31b88c4a958 from 1 unit to 519 units.

Important Notes:

• Override headers are internal to MagicAPI and are not visible to end users.

• Ensure that override-request-id it matches the original x-request-id.

• This method allows fine-tuning billing based on actual resource consumption, providing accurate tracking when results are available.

---

Method 2: Overwriting Usage with /[apiStoreSlug]/overrideCustomUsage

This method provides an alternative way to adjust API usage after the initial request using a dedicated endpoint. It is best suited when the final resource usage is known after the processing is complete.

Endpoint Details:

• Endpoint: /[apiStoreSlug]/overrideCustomUsage

• Method: POST

• Availability: Restricted to API store creators.

• Update Window: The update must be made within 6 hours after the initial request.

• ADMIN_API_KEY: You can find you Admin API Key at -> https://api.market/seller/[YourAPIStoreSlug]/apiKeys

Example Request:

curl --location 'https://api.magicapi.dev/api/v2/pipfeed/overrideCustomUsage' \
--header 'accept: application/json' \
--header 'x-magicapi-key: ADMIN_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "data": {
        "overrideRequestId": "f8e1d576-a460-4847-8683-c31b88c4a958",
        "overrideCustomUsage": "API=812;"
    }
}'

Parameters:

• overrideRequestId: The ID of the original request to update. This should match the x-request-id from the initial request.

• overrideCustomUsage: A string specifying the new usage value (e.g., API=8.1;). This updates the recorded usage to reflect the actual resources consumed by the request.

Use Case: This method is particularly useful when the job’s final resource consumption becomes clear after some time, such as after processing a complex background job or AI task. It allows API store creators to adjust the recorded usage without needing a user-triggered result retrieval.

Potential Errors:

• Unauthorized Access: If the request is made by a user other than the API store creator.

• Time Limit Exceeded: If the override is attempted after the 2-hour window.

• Invalid Input: Issues like missing parameters or incorrect data format.

Additional Condition: Records can only be updated for API calls made within the last 6 hours. If an attempt is made to override usage for a request that was initiated more than 6 hours ago, the request will fail. This restriction ensures that updates remain timely and relevant, preventing adjustments for outdated requests.

Key Considerations:

• Only API store creators can access this endpoint, ensuring control over usage adjustments.

• Adjustments must be made within a 6-hour window from the original request time.

• Provides flexibility to adjust billing based on actual usage, maintaining transparency with API consumers.

---

Summary

MagicAPI offers two methods to adjust API usage after an initial request, ensuring accurate billing for varying use cases:

1. Overriding Usage on Result Retrieval: Adjust usage when a user retrieves the result, using custom headers for precision.

2. Overwriting Usage via /overrideCustomUsage Endpoint: Directly update usage through a secure endpoint, ideal for scenarios where the final usage is determined after processing.

Both methods allow API developers and sellers to fine-tune billing based on real-world resource consumption, enhancing transparency and fairness in API usage tracking.

---

---