Skip to main content
GET
Fetch Data Table Records

Overview

This endpoint returns the records of a data table — the rows Qobra synchronizes from your CRM, database or files, and the ones created in Qobra — as they stand before any commission calculation. Use this endpoint for:
  • Replicating a data table into a data warehouse
  • BI dashboards on the data your plans read
  • Checking what Qobra imported from a source
Data tables = inputs. This endpoint gives you the rows your plans read. What each row contributed to commissions comes from record reporting.
Discover the ids with GET /v2/data-structures, where every data table is listed with "type": "data_table". A data table belongs to no environment: unlike a reporting table or a quota, its id works whichever environment you copied it from in the Qobra app.

Your first call

Example response


What a record holds

Every record starts with two identifiers, then carries one key per field of the table:
  • standard.id — the id of the record in Qobra.
  • standard.source_id — its id in the source system, such as a Salesforce opportunity id. A record created in Qobra carries its own standard.id there, as the second record above does.
  • datatable.<key> — one per field. The keys are specific to your table: read them from GET /v2/data-structures/{table_id}/fields rather than guessing them from the field names.
Each value follows the type of its field: A link points at a record of another table. Its id is the source id of that record, not its Qobra id, so it matches the standard.source_id you read from the linked table. An empty link reads { "id": null, "name": null }. A link whose target Qobra has not resolved yet carries its id with a null name. An amount carries the currency of its own value, so a page can mix currencies within the same field.

Records created in Qobra are included

A table synchronized from an integration can also hold records created by hand in Qobra. This endpoint returns both: it reads the whole table, whatever the origin of each record. Tell them apart with standard.source_id, which equals standard.id on a record created in Qobra.

Pagination

Pages are linked: every response carries a next_url that already includes your limit and any date filters you sent. Follow it until has_more is false.
Two things worth knowing:
  • limit defaults to its maximum, 2000. Omitting it gives you the largest page, not a small one. It is validated rather than capped, so ?limit=5000 returns 400 instead of 2000 rows.
  • Records come in creation order.

Filtering by modification date

last_modified_after and last_modified_before restrict the response to records modified inside a window. Both bounds are inclusive, and they cannot be equal — passing the same datetime twice returns 400.
Always include the timezone in your timestamp, as in the example above.
Deleted records are never returned, so an incremental sync does not see a record disappear. Fetch the whole table again periodically, and remove from your copy the records deleted in Qobra or in the source.

Selecting fields

The endpoint returns every field of the table by default. Pass fields to receive only the ones you need:
  • The values are api_keys, as listed by GET /v2/data-structures/{table_id}/fields, separated by commas. The keys above are examples: read yours from that endpoint.
  • standard.id and standard.source_id are always returned, whether you list them or not.
  • A record keeps the table’s order of fields, not the order of your list. Spaces around a key and duplicate keys are ignored.
  • next_url keeps your selection. If you build the next URL yourself from next_start_id, pass fields again.
  • Without fields, nothing changes: every field is returned.

Why select fields

A page holds one value per field and per record, so fewer fields make faster and lighter pages. On a table of 186 fields, keeping 50 divides the server time of a page by about three and its compressed size by about four. For a full extraction of a wide table, list only the fields your warehouse uses.

Unknown keys

A key the fields endpoint does not list returns 400, naming every unknown key:
A key can change, for instance when a metric is renamed. If a sync that used to work starts failing on fields, read the fields endpoint again and update your list. A list left empty (fields=) returns 400 too.

How many fields fit in the URL

The server accepts request lines of up to 4,094 bytes. The rest of the URL (the path, start_id, limit and the date filters) takes about 300 bytes. That leaves about 3,790 bytes for the value of fields. Count start_id from your first call: next_url adds it to every next page. Each key costs its length plus 3 bytes, the size of a comma once encoded (%2C). Plan on about 70 fields with typical keys, and work it out for yours when they are long.
A URL over the limit is refused before it reaches the API. You receive a 400 Bad Request in text/html, not in the JSON error format above, and its body contains Request Line is too large. Remove fields from your list, or drop fields to receive every field.

Errors

Qobra also returns 404 for the id of a reporting table or of a quota, which have endpoints of their own. It does the same for the id of a table Qobra generates from your plans’ results. GET /v2/data-structures does not list those tables either: their results come from record reporting and statements.
This endpoint is the v2 counterpart of the v1 fetch data table records endpoint, which stays maintained. Moving to v2 is optional: see the migration guide.

Authorizations

X-API-Key
string
header
required

Your Qobra API key. Generate it from Settings > API Keys in Qobra.

Path Parameters

data_table_id
string<ObjectId>
required

ID of a data table (from /v2/data-structures, where it is listed with type data_table)

Query Parameters

start_id
string<ObjectId>

Start after this record ID (for ID-based pagination, recommended)

limit
integer
default:2000

Number of records per page (1-2000)

Required range: 1 <= x <= 2000
last_modified_after
string<date-time>

ISO 8601 datetime - Only return records modified after this timestamp (for incremental sync)

last_modified_before
string<date-time>

ISO 8601 datetime - Only return records modified before this timestamp

fields
string

Comma-separated api_keys of the fields to return, as listed by /v2/data-structures/{table_id}/fields (e.g. datatable.amount,datatable.close_date). standard.id and standard.source_id are always returned. When omitted, every field is returned. A key the fields endpoint does not list returns 400.

Response

Successfully retrieved the records of the data table, with pagination metadata for navigating through large datasets.

data
object[]
required

List of records

meta
object
required