API Overview

API Overview

Welcome to the AdEx API v2.0 documentation. This page covers essential information about working with the AdEx API, including query parameters, rate limits, error handling, and best practices.

Query Parameters

The Hood API uses URL query parameters for filtering, sorting, searching, and paginating data. These parameters work across all collection endpoints (endpoints that return lists of resources).

Filtering

Filter data using query parameters with optional operators.

Basic filtering:

GET /v1/hood/campaigns?status=active&is_draft=false

This returns campaigns where status equals “active” AND is_draft equals “false”.

Using operators:

Template: [parameter_name]=[operator:][value]

GET /v1/hood/campaigns?status=neq:paused&is_draft=eq:false

Supported operators:

Multiple values (IN operator):

GET /v1/hood/campaigns?status=in:active,scheduled,running

Returns campaigns with status “active”, “scheduled”, or “running”.

Range filtering:

GET /v1/hood/campaigns?created_at=r:2024-01-01,2024-12-31

Returns campaigns created between January 1, 2024 and December 31, 2024.

Sorting

Sort results using the sort query parameter. Sorts the response by specified field(s) with the option to specify sorting order (ascending by default, add prefix - for descending).

Ascending order (default):

GET /v1/hood/campaigns?sort=name

Sorts by name ascending.

Descending order (prefix with -):

GET /v1/hood/campaigns?sort=-id

Sorts by id descending.

Multiple sort fields:

GET /v1/hood/campaigns?sort=id,-name

Sorts by id ascending, then by name descending.

Pagination

Paginate through large datasets using the page query parameter. The page number indicates which set of items will be returned in the response.

Format: page=N,M

• N (required) - Page number
• M (optional) - Number of items per page (defaults to resource-specific setting)

Examples:

Page 1 with 20 items:

GET /v1/hood/campaigns?page=1,20

Returns page 1 with 20 items.

Page 2 with 20 items:

GET /v1/hood/campaigns?page=2,20

Returns page 2 with 20 items (items 21-40).

Page 3 with default items:

GET /v1/hood/campaigns?page=3

Returns page 3. The number of objects returned depends on the resource settings (typically 10 items by default).

Partial Representation

Request only specific fields to reduce response size and improve performance. The Hood API provides two ways to control which fields are returned in the response.

Using the fields parameter:

The fields parameter represents an array of dimensions and measures. Dimensions are used to categorize, segment, and reveal the details of the data. Measures contain numeric, quantitative values that can be measured.

GET /v1/hood/campaigns?fields=id,name,status,creator

Returns only the specified fields: id, name, status, and creator.

Using the view parameter:

The view parameter provides predefined field sets for common use cases.

GET /v1/hood/campaigns?view=full

Returns full representation of the resource with all available fields.

Available views:

• Default view (if not specified) - Returns commonly used fields
• full - Returns complete representation with all fields

Search

Search across resources using the q query parameter (a search term or keyword) combined with the q_fields parameter to specify which fields to search.

Basic search (searches default field):

GET /v1/hood/campaigns?q=Holiday

Searches for “Holiday” in the default search field.

Search specific field:

Use the q_fields parameter to list all fields you want to include in the search.

GET /v1/hood/campaigns?q=promo&q_fields=name

Returns campaigns whose name contains the string “promo”.

Search multiple fields:

GET /v1/hood/campaigns?q=summer&q_fields=name,description,labels

Returns campaigns that contain the string “summer” in any of the specified fields (name, description, or labels).

Combining Parameters

You can combine multiple query parameters in a single request for powerful, precise queries:

GET /v1/hood/campaigns?status=active&sort=-created_at&page=1,20&fields=id,name,status,created_at&q=summer&q_fields=name,description

This query:

• Filters campaigns where status is “active”
• Searches for “summer” in name and description fields
• Sorts by created_at descending (newest first)
• Paginates to page 1 with 20 items per page
• Returns only id, name, status, and created_at fields

This combination significantly reduces response size and network traffic while providing exactly the data you need.

Rate Limits

Ocamba’s APIs apply rate limits on the number of requests to ensure a stable and reliable service for all clients. Please consult our API reference section to learn rate limits for each endpoint.

All API endpoints for rate limits are on a per-account basis and use a fixed-time-window rate limiting algorithm with two windows: a 1-second window and a 1-minute window.

All API traffic is subject to these rate limits and will receive an HTTP 429 status code (Too many requests) if a rate limit is reached.

All API endpoints use one of the following rate limits.

All responses that haven’t hit the limit will contain the HTTP response headers that indicate how much of your allowed request limit has been used and how much is left during that time window.

Make sure to use these headers to control your request rate, particularly if you’re operating a 3rd-party app that sends requests on behalf of Ocamba customers.

Response headers

• X-RateLimit-Limit: The total number of requests permitted within a current time window.

• X-RateLimit-Remaining: The estimated number of requests you can still make during the current time window.

• X-RateLimit-Reset: The number of seconds left until the rate limit window refreshes.

What does Retry-After: -1 mean?

The value -1 signifies that your client has hit the parallel concurrency limit (i.e., the number of simultaneous requests allowed has been exceeded).

In this scenario, we cannot provide a reliable retry time because the retry window depends on when one of your in-flight requests completes.

Unlike rate limiting based on a fixed time window, parallel limits are dynamic and depend on current usage.

Query Param Rate Limits

If you request any subresource (additional) fields on a parent resource through the fields query parameter, you will have a stricter (lower) rate limit.

In the following examples campaigns is a parent resource while creator and account are subresources.

Examples

If you're making an HTTP GET request to /v1/hood/campaigns?fields=id,company_id,creator_id,creator your requests will be at a lower rate limit than if you had not requested additional information. Similarly, a GET request to /v1/hood/campaigns?fields=id,company_id,account_id,account will result in a lower rate limit than a call to /v1/hood/campaigns?fields=id,company_id without specifying *account* as an additional field.

Note that each call may consume rate limits from multiple endpoints when subresources are requested. For example, let's assume we have 150 calls per minute on /v1/hood/campaigns, 50 calls per minute on /v2/ocamba/accounts, and 50 calls per minute on /v2/ocamba/members. When subresources like account or creator are included using the fields query parameter, rate limits are deducted from the parent endpoint (/campaigns).

This means that although you’re making a single request to /campaigns, the API internally performs additional lookups (e.g., for account or creator), each of which counts against that specific subresource’s rate limit.

GET /v1/hood/campaigns?fields=id,account_id,account and GET /v1/hood/campaigns?fields=id,account_id,account,creator_id,creator are still counted only against the /v1/hood/campaigns endpoint.

Even if subresources like account and creator are included via the fields parameter, the rate limit for those additional resources is not affected. Instead, each of those calls counts as multiple calls against the /campaigns endpoint itself.

For example, the last request would count as 3 calls on /campaigns, leaving you with 147 calls remaining out of 150 — while /accounts and /members limits stay untouched.

The rate limits on all of these calls reset at the same window. Similar rules apply for burst limits.

Response Status Codes

Our API uses conventional HTTP response status codes to indicate success or failure of an API request. Response status codes typically fall into the following three ranges:

• 2xx - Success
• 4xx - Error as a result of information provided as part of the request, such as a requested object that doesn’t exist, an invalid setting, etc.
• 5xx - Error due to server issues or service unavailability.

See the table below for a list of status codes and their corresponding descriptions:

Error Response Format

When a request is unsuccessful, the API returns an error response with the following structure:

{
  "code": 400,
  "title": "Bad request.",
  "message": "The request body is not valid.",
  "trace_id": "99a84211-f73d-4ff8-acdf-eb3e06bb9d62"
}

Error fields:

• code: The HTTP status code (e.g., 400, 500)
• title: A brief summary of the error
• message: Detailed explanation of what went wrong (may be omitted for 5xx errors)
• trace_id: A unique identifier for this error instance, useful when contacting support

Examples

400 Bad Request:

{
  "code": 400,
  "title": "Bad request.",
  "message": "The request body is not valid.",
  "trace_id": "99a84211-f73d-4ff8-acdf-eb3e06bb9d62"
}

500 Internal Server Error:

{
  "code": 500,
  "title": "Internal server error.",
  "trace_id": "99a84211-f73d-4ff8-acdf-eb3e06bb9d62"
}

Retries

We recommend watching for 429 and 503 error codes and building in a retry mechanism. The retry mechanism should follow an exponential backoff schedule to reduce request volume when necessary. Be sure to build in some randomness into the backoff schedule to avoid a thundering herd effect.